Swagger-告别手写文档

1. 引言

• 在RESTful API开发中，维护准确、易读的接口文档是团队协作的核心挑战，通常接口文档分为离线的和实时的。离线的接口文档工具有 YAPI等，其中最大的弊端是接口程序发生变动时需要及时更新接口文档，十分麻烦。实时接口文档就是可以根据我们的代码来自动生成相应的接口文档，优点就是我们的代码发生变化时，生成的接口文档也会自动更新，无需我们关注修改，只需要按时发布即可。但是由于是根据代码自动生成的，所以最大的弊端就是代码侵入性强，需要我们在项目代码中集成生成接口文档的相关代码。实时接口文档现在的方案有很多，但是Swagger还是其中比较有影响力的一个。

2. Swagger是什么？

Swagger是一套基于OpenAPI规范的工具生态，通过自动化生成交互式文档和测试工具，解决了API设计、调试与协作的痛点，其核心价值是定义即文档，文档即测试。包含：

1. Swagger Editor：可视化编写API定义的编辑器。
2. Swagger UI：一个无依赖的HTML、JS和CSS集合，自动生成可交互的API文档页面。
3. Swagger Codegen：个模板驱动引擎，根据API定义生成客户端/服务端代码。

3. SpringBoot2.7.3集成Swagger

• knife4j是为Java MVC框架集成Swagger生成Api文档的增强解决方案，基于Swagger的国产开源工具，提供更强大的API文档界面和功能扩展，目前，一般都使用knife4j框架。其核心优势如下：
  1. 更美观的UI界面，支持Markdown文档补充。
  2. 动态调试参数、离线文档导出（PDF/Word）。
  3. 接口权限控制、全局参数配置等企业级功能。

1. 添加依赖：

   <dependency>
       <groupId>com.github.xiaoymin</groupId>
       <artifactId>knife4j-spring-boot-starter</artifactId>
       <version>3.0.3</version>
   </dependency>
   

2. 配置Swagger基本信息：

   @Configuration
   public class Knife4jConfig {
       @Bean
       public Docket docket(Environment environment) {
            // 设置环境范围
           Profiles profiles = Profiles.of("dev","test");
           // 如果在该环境返回内则返回：true，反之返回 false
           boolean flag = environment.acceptsProfiles(profiles);
   
           Docket docket = new Docket(DocumentationType.SWAGGER_2)
               	.enable(flag)
                   .apiInfo(getApiInfo())
                   .select() //设置扫描接口
                   .apis(RequestHandlerSelectors
                           //.any() // 扫描全部的接口，默认
                           //.none() // 全部不扫描
                           //.withClassAnnotation(RestController.class) // 扫描带有指定注解的类下所有接口
                           //.withMethodAnnotation(PostMapping.class) // 扫描带有只当注解的方法接口
                         .basePackage("com.clx.controller"))//扫描指定包下的接口，最为常用
                   .paths(PathSelectors
                          .any()) //满足条件的路径，该断言总为true
               		   //.none() // 不满足条件的路径，该断言总为false（可用于生成环境屏蔽 swagger）
                          //.ant("/user/**") // 满足字符串表达式路径
                          //.regex("") // 符合正则的路径
                   .build();
           return docket;
       }
   
       //文档相关信息
       private ApiInfo getApiInfo() {
           return new ApiInfoBuilder()
                   .title("宠物项目测试标题")
                   .description("宠物项目测试接口文档")
                   .version("1.0")
                   .contact(new Contact("芝士小霸王龙", "https://example.com", "contact@example.com"))
                   .build();
       }
   
       protected void addResourceHandlers(ResourceHandlerRegistry registry) {
           registry.addResourceHandler("/doc.html").addResourceLocations("classpath:/META-INF/resources/");
           registry.addResourceHandler("/webjars/**").addResourceLocations("classpath:/META-INF/resources/webjars/");
       }
   
   }
   

3. 当SpringBoot版本过高时需要在application.yml中配置如下信息：

   server:
    port: 8080
   spring:
     profiles:
       active:	dev #建议在开发环境中使用
     mvc:
       pathmatch:
         matching-strategy: ANT_PATH_MATCHER
   

   访问http://localhost:8080/doc.html访问接口文档。

   

4. 常见注解

1. 通过注解可以控制生成的接口文档，使接口文档拥有更好的可读性，以下是对 Swagger2（springfox） 和 Swagger3（OpenAPI 3.0，springdoc） 常用注解的对比：

   功能	Swagger2（springfox）	Swagger3（springdoc-openapi）
   文档入口注解	@EnableSwagger2	@OpenAPIDefinition
   接口分组/分类	@Api(tags = "用户模块")	@Tag(name = "用户模块")
   接口方法描述	@ApiOperation("查询用户")	@Operation(summary = "查询用户")
   参数描述	@ApiParam("用户ID")	@Parameter(description = "用户ID")
   响应模型定义	@ApiResponse(code=200, message="成功")	@ApiResponse(responseCode="200", description="成功")
   实体类字段说明	@ApiModelProperty("用户名")	@Schema(description = "用户名")
   隐藏接口/类	@ApiIgnore	@Hidden
   安全认证配置	无直接注解（需配置SecurityScheme类）	@SecurityScheme（支持OAuth2、JWT等

2. 常用注解示例：

   1. 接口类定义：

      @Api(tags = "用户管理")
      @RestController
      public class UserController {}
      
      @Tag(name = "用户管理")
      @RestController
      public class UserController {}
      

   2. 接口方法描述：

      @ApiOperation(value = "创建用户", notes = "需提供用户名和密码")
      @PostMapping("/user")
      public User createUser(@ApiParam("用户对象") @RequestBody User user) {}
      
      @Operation(summary = "创建用户", description = "需提供用户名和密码")
      @PostMapping("/user")
      public User createUser(@Parameter(description = "用户对象") @RequestBody User user) {}
      

   3. 实体类字段说明：

      @ApiModel("用户实体")
      public class User {
          @ApiModelProperty(value = "用户ID", example = "1001")
          private Long id;
      }
      
      @Schema(name = "用户实体")
      public class User {
          @Schema(description = "用户ID", example = "1001")
          private Long id;
      }