swagger是一个自动生成接口文档的工具，在需求不断变更的环境下，手动编写文档的效率实在太低。与swagger2相比新版的swagger3配置更少，使用更加方便。

开始使用

springboot 版本：2.5.2

pom中引入Swagger依赖

<dependency>
     <groupId>io.springfox</groupId>
      <artifactId>springfox-boot-starter</artifactId>
      <version>3.0.0</version>
</dependency>

启动类开启swagger

@SpringBootApplication
@EnableOpenApi
public class SwaggerApplication {

    public static void main(String[] args) {
        SpringApplication.run(SwaggerApplication.class, args);
    }

}

配置类：

@Configuration
public class SwaggerConfig {

    @Bean
    public Docket docket(){
        return new Docket(DocumentationType.OAS_30)
                .apiInfo(apiInfo())
                .enable(true)
                .groupName("Nicander")
                .select()
                .apis(RequestHandlerSelectors.withClassAnnotation(Api.class))
                .paths(PathSelectors.any())
                .build();
    }

    public ApiInfo apiInfo(){
        return new ApiInfoBuilder()
                .title("Swagger 3")
                .description("Swagger 3")
                .contact(new Contact("name","主页","email"))
                .version("1.0")
                .build();
    }

@Configuration
public class SwaggerConfig {

    @Bean
    public Docket docket(){
        return new Docket(DocumentationType.OAS_30)
                // 设置Api元信息
                .apiInfo(apiInfo())
                .enable(true)

                // 选择在swagger-ui中发布地址
                .select()
                .apis(RequestHandlerSelectors.withClassAnnotation(Api.class))
                .paths(PathSelectors.any())
                .build()
                // 设置安全模式,设置token访问
                .securitySchemes(securitySchemes())
                .securityContexts(securityContexts());
    }

    public ApiInfo apiInfo(){
        return new ApiInfoBuilder()
                .title("Swagger 3")
                .description("Swagger 3")
                .contact(new Contact("name","主页","email"))
                .version("1.0")
                .build();
    }

    /**
     * 安全模式，这里指定token通过Authorization头 请求头传递
     */
    private List<SecurityScheme> securitySchemes() {
        List<SecurityScheme> securitySchemes = new ArrayList<>();
        securitySchemes.add(new ApiKey("Authorization", "Authorization", "header"));
        return securitySchemes;
    }

    /**
     * 安全上下文
     */
    private List<SecurityContext> securityContexts() {
        List<SecurityContext> securityContexts = new ArrayList<>();
        securityContexts.add(SecurityContext.builder()
                .securityReferences(defaultAuth())
                .build());
        return securityContexts;
    }

    /**
     * 默认安全上下文引用
     */
    private List<SecurityReference> defaultAuth() {
        AuthorizationScope authorizationScope = new AuthorizationScope("global", "accessEverything");
        AuthorizationScope[] authorizationScopes = new AuthorizationScope[1];
        authorizationScopes[0] = authorizationScope;
        List<SecurityReference> securityReferences = new ArrayList<>();
        securityReferences.add(new SecurityReference("Authorization", authorizationScopes));
        return securityReferences;
    }
}
}

controller类：

@Api
@RestController
@RequestMapping("/swagger")
public class HelloWordController {

    @ApiOperation("swagger 3")
    @GetMapping()
    public String swagger3(){
        return "swagger3";
    }
}

项目启动后，浏览器访问http://localhost:8080/swagger-ui/index.html

常用注解

@Api

@Api注解用于接口类上，用于对接口类定义相关说明。

实际使用中，@Api注解常用的属性只有tags，该属性起到对类中的接口进行分组的作用。

@ApiOperation

@ApiOperation用在请求的方法上，说明方法的用途、作用。

@ApiOperation注解常用属性包括：

    @ApiOperation(value = "ApiOperation接口",notes = "notes")
    @GetMapping("/api")
    public String swagger3(String hello){
        return "swagger3";
    }

swagger-ui中效果

@ApiImplicitParams

• @ApiImplicitParams：用在请求的方法上，表示一组参数说明，一般用与Get请求
  • @ApiImplicitParam：用在@ApiImplicitParams注解中，指定一个请求参数的各个方面
    - name：参数名
    • value：参数的汉字说明、解释
    • required：参数是否必须传
    • paramType：参数放在哪个地方
      · header —> 请求参数的获取：@RequestHeader
      · query —> 请求参数的获取：@RequestParam
      · path（用于restful接口）—> 请求参数的获取：@PathVariable
      · div（不常用）
      · form（不常用）
      dataType：参数类型，默认String，其它值dataType=”Integer”
      defaultValue：参数的默认值

      @ApiResponses

      @ApiResponses：用在请求的方法上，表示一组响应
      @ApiResponse：用在@ApiResponses中，一般用于表达一个错误的响应信息
      code：数字，例如400
      message：信息，例如”请求参数没填好”
      response：抛出异常的类

      @ApiModel

      @ApiModel：用于响应类上，表示一个返回响应数据的信息
      （这种一般用在post创建的时候，使用@RequestBody这样的场景，
      请求参数无法使用@ApiImplicitParam注解进行描述的时候）

      @ApiModelProperty

      
      @ApiModelProperty：用在属性上，描述响应类的属性

swagger-ui

参考

https://www.5axxw.com/wiki/topic/galhwk