Spring Boot中使用Swagger3生成API文档

Swagger 是一套基于 OpenAPI 规范（OpenAPI Specification，OAS）构建的开源工具， 提供了一套通过代码和注解自动生成文档的方法，可以帮助我们设计、构建、记录以及使用 Restful API。

1.pom.xml中添加Swagger3依赖

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

2. 主程序启动类添加@EnableOpenApi注解

@SpringBootApplication
@EnableOpenApi
public class ****Application {
    public static void main(String[] args) {
        SpringApplication.run(****Application.class, args);
    }
}

3 配置类

@Configuration
public class SwaggerConfig {
    Boolean swaggerEnabled=true;
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.OAS_30).apiInfo(apiInfo())
                // 是否开启
                .enable(swaggerEnabled).select()
                // 扫描的路径包
                .apis(RequestHandlerSelectors.basePackage("controller所在包"))
                // 指定路径处理PathSelectors.any()代表所有的路径
                .paths(PathSelectors.any()).build().pathMapping("/");
    }

    private ApiInfo apiInfo() {
        Calendar c = Calendar.getInstance(TimeZone.getTimeZone("GMT+08:00"));    //获取东八区时间
        SimpleDateFormat s = new SimpleDateFormat("yyyy-MM-dd");
        String curDate = s.format(c.getTime());
        return new ApiInfoBuilder()
                .title("项目API文档")
                .description(curDate + " 发布")
                .version("V1.0")
                .build();
    }
}

4. 文档地址

https://ip:port/context-path/swagger-ui/index.html

5. Controller层注解

• @Api：用在请求的类上，表示对类的说明
  tags=“说明该类的作用，可以在UI界面上看到的注解”
  value=“该参数没什么意义，在UI界面上也看到，所以不需要配置”

• @ApiOperation：用在请求的方法上，说明方法的用途、作用
  value=“说明方法的用途、作用”
  notes=“方法的备注说明”

• @ApiImplicitParams：用在请求的方法上，表示一组参数说明

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

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

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

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