Swagger使用教程

个人笔记,不喜勿喷

第一步:导依赖

    <!--swagger2的核心包-->
    <dependency>
        <groupId>io.springfox</groupId>
        <artifactId>springfox-swagger2</artifactId>
        <version>2.9.2</version>
    </dependency>
    <!--swagger2的ui界面包  底层用的thymeleaf-->
    <dependency>
        <groupId>io.springfox</groupId>
        <artifactId>springfox-swagger-ui</artifactId>
        <version>2.9.2</version>
    </dependency>

第二步:

配置类 :  SwaggerConfig 

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.ParameterBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.schema.ModelRef;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.service.Parameter;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
import java.util.ArrayList;
import java.util.List;

@Configuration
@EnableSwagger2
public class SwaggerConfig {
    @Bean
    public Docket createRestApi() {
        List<Parameter> pars = new ArrayList<>();
        pars.add(new ParameterBuilder()
                .name("token")
                .description("token")
                .required(false)
                .parameterType("header")
                .modelRef(new ModelRef("string"))
                .build()
        );
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                //对外暴露服务的包,以controller的方式暴露,所以就是controller的包.
                .apis(RequestHandlerSelectors.basePackage("cn.xia"))
                .paths(PathSelectors.any())
                .build().globalOperationParameters(pars);
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("宠物乐园api")
                .description("宠物乐园接口文档说明")
                .contact(new Contact("tom", "", "tom@itsource.cn"))
                .version("1.0")
                .build();
    }
}

@Api： 用于类，标识这个类是swagger的资源
@ApiIgnore： 用于类，忽略该 Controller，指不对当前类做扫描
@ApiOperation： 用于方法，描述 Controller类中的 method接口
@ApiParam： 用于参数，单个参数描述，与 @ApiImplicitParam不同的是，他是写在参数左侧的。如（ @ApiParam(name="username",value="用户名")Stringusername）
@ApiModel： 用于类，表示对类进行说明，用于参数用实体类接收
@ApiProperty：用于方法，字段，表示对model属性的说明或者数据操作更改
@ApiImplicitParam： 用于方法，表示单独的请求参数
@ApiImplicitParams： 用于方法，包含多个 @ApiImplicitParam
@ApiResponse： 用于方法，描述单个出参信息
@ApiResponses： 用于方法，包含多个@ApiResponse
@ApiError： 用于方法，接口错误所返回的信息

第三部:controller层加注解

@Api(value = "/",description = "登录相关的类2")----介绍该类

//ApiOperation ----用来介绍该接口的作用
//value  -- 参数的注解 
// required  --是否为必填项
//example  --举例说明

@ApiOperation("获取图形验证码接口")    
@GetMapping("/graphics/{imageCodeKey}")
public JSONResult getVerifyCode(@ApiParam(value = "注册手机号",required = true,example = "17596325874") @PathVariable("imageCodeKey") String key){
    String baseStr = iverifyCodeservice.getVerifyCode(key);
    //把返回的数据封装到JSONResult中,给页面
    log.info(baseStr);
    return JSONResult.success(baseStr);
}

如果你传入的是一个对象,并且想给对象的每一个字段加上注解

对象如下

/**
 * description -----对象描述
 * value     ------对象介绍
 * required ----  是否必填项
 * value   ----- 注解
 */
@ApiModel(description = "会员登录账号实体类",value = "会员登录账号对象")
public class User extends Model<User> {

    @TableId(value = "id", type = IdType.AUTO)
    @ApiModelProperty(required = true,value = "id")
    private Long id;

    @TableField("create_time")
    @ApiModelProperty(required = true,value = "创建时间")
    private Long createTime;

    @TableField("update_time")
    @ApiModelProperty(required = true,value = "修改时间")
    private Long updateTime;
    /**
     * 三方登录名
     */
    @TableField("third_uid")
    @ApiModelProperty(required = true,value = "三方登录名")
    private String thirdUid;
    /**
     * 手机号
     */
    @ApiModelProperty(required = true,value = "电话")
    private String phone;
    /**
     * 邮箱
     */
    @ApiModelProperty(required = true,value = "邮箱")
    private String email;
    /**
     * 昵称
     */
    @ApiModelProperty(required = true,value = "昵称")
    @TableField("nick_name")
    private String nickName;
    /**
     * 用户状态
     */
    @ApiModelProperty(required = true,value = "用户状态")
    @TableField("bit_state")
    private Long bitState;
    /**
     * 安全级别
     */
    @ApiModelProperty(required = true,value = "安全级别")
    @TableField("sec_level")
    private Integer secLevel;

    @ApiModelProperty(required = true,value = "登录id")
    @TableField("login_id")
    private Long loginId;
}

接口如下

@ApiOperation("保存和修改公用的")
@RequestMapping(value="/save",method= RequestMethod.POST)
public JSONResult saveOrUpdate( @ApiParam("传入对象") @RequestBody User user){
    if(user.getId()!=null){
        userService.updateById(user);
    }else{
        userService.insert(user);
    }
    return JSONResult.success();
}

效果图 : 

微服务

依赖一样的加

需要多加两个配置类

package cn.itsource.config;

import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.http.HttpStatus;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;
import reactor.core.publisher.Mono;
import springfox.documentation.swagger.web.*;

import java.util.Optional;

@RestController
@RequestMapping("/swagger-resources")
public class SwaggerHandler {

    @Autowired(required = false)
    private SecurityConfiguration securityConfiguration;

    @Autowired(required = false)
    private UiConfiguration uiConfiguration;

    private final SwaggerResourcesProvider swaggerResources;
 
    @Autowired
    public SwaggerHandler(SwaggerResourcesProvider swaggerResources) {
        this.swaggerResources = swaggerResources;
    }
 
 
    @GetMapping("/configuration/security")
    public Mono<ResponseEntity<SecurityConfiguration>> securityConfiguration() {
        return Mono.just(new ResponseEntity<>(
                Optional.ofNullable(securityConfiguration).orElse(SecurityConfigurationBuilder.builder().build()), HttpStatus.OK));
    }
 
    @GetMapping("/configuration/ui")
    public Mono<ResponseEntity<UiConfiguration>> uiConfiguration() {
        return Mono.just(new ResponseEntity<>(
                Optional.ofNullable(uiConfiguration).orElse(UiConfigurationBuilder.builder().build()), HttpStatus.OK));
    }
 
    @GetMapping("")
    public Mono<ResponseEntity> swaggerResources() {
        return Mono.just((new ResponseEntity<>(swaggerResources.get(), HttpStatus.OK)));
    }
}

package cn.itsource.config;

import lombok.AllArgsConstructor;
import org.springframework.cloud.gateway.config.GatewayProperties;
import org.springframework.cloud.gateway.route.RouteLocator;
import org.springframework.cloud.gateway.support.NameUtils;
import org.springframework.context.annotation.Primary;
import org.springframework.stereotype.Component;
import springfox.documentation.swagger.web.SwaggerResource;
import springfox.documentation.swagger.web.SwaggerResourcesProvider;

import java.util.ArrayList;
import java.util.List;

@Component
@Primary
@AllArgsConstructor
public class SwaggerProvider implements SwaggerResourcesProvider {
    public static final String API_URI = "/v2/api-docs";
    private final RouteLocator routeLocator;
    private final GatewayProperties gatewayProperties;


    @Override
    public List<SwaggerResource> get() {
        List<SwaggerResource> resources = new ArrayList<>();
        List<String> routes = new ArrayList<>();
        routeLocator.getRoutes().subscribe(route -> routes.add(route.getId()));
        gatewayProperties.getRoutes().stream().filter(routeDefinition -> routes.contains(routeDefinition.getId()))
                .forEach(routeDefinition -> routeDefinition.getPredicates().stream()
                        .filter(predicateDefinition -> ("Path").equalsIgnoreCase(predicateDefinition.getName()))
                        .forEach(predicateDefinition -> resources.add(swaggerResource(routeDefinition.getId(),
                                predicateDefinition.getArgs().get(NameUtils.GENERATED_NAME_PREFIX + "0")
                                        .replace("/**", API_URI)))));
        return resources;
    }
    private SwaggerResource swaggerResource(String name, String location) {
        SwaggerResource swaggerResource = new SwaggerResource();
        swaggerResource.setName(name);
        swaggerResource.setLocation(location);
        swaggerResource.setSwaggerVersion("2.0");
        return swaggerResource;
    }
}

网页访问:http://localhost:10030/swagger-ui.html#/product-controller/AddUsingPOST