一、引入依赖
<!--Swagger-UI API文档生产工具--><dependency><groupId>io.springfox</groupId><artifactId>springfox-boot-starter</artifactId><version>3.0.0</version></dependency><!--解决Swagger访问主页时的NumberFormatException问题--><dependency><groupId>io.swagger</groupId><artifactId>swagger-models</artifactId><version>1.6.0</version></dependency><dependency><groupId>io.swagger</groupId><artifactId>swagger-annotations</artifactId><version>1.6.0</version></dependency><!-- 排除低版本的spring-plugin-core--><dependency><groupId>org.springframework.boot</groupId><artifactId>spring-boot-dependencies</artifactId><version>${boot.version}</version><type>pom</type><scope>import</scope><exclusions><exclusion><groupId>org.springframework.plugin</groupId><artifactId>spring-plugin-core</artifactId></exclusion></exclusions></dependency><!-- 引入高版本的spring-plugin-core--><dependency><groupId>org.springframework.plugin</groupId><artifactId>spring-plugin-core</artifactId><version>2.0.0.RELEASE</version></dependency>二、代码添加注解
controller类添加注解@Tag(name="分组名xxx", description = "这是描述")，
controller方法添加注解@Operation(tags = "分组名xxx", description = "这是描述")
保证@Operation注解中的tags的值与@Tag注解中的name的值一致，这样导出的接口会自动在yapi中创建分组
代码示例
@Tag(name = "等级接口分组", description = "等级相关接口api")
@RestController
@RequestMapping("/grade")
public class GradeController {@Autowiredprivate IGradeService gradeService;/*** 新增规则* @param requestDTO* @return*/@Operation(tags = "等级接口分组", description = "新增规则")@PostMapping("/rule/create")public WebResult createRule(@RequestBody @Valid RuleGradeCreateRequestDTO requestDTO) {return gradeService.createRule(requestDTO);}
}入参/出参对象添加注解@Schema(description = "请求入参的描述"))
入参
@Schema(description = "请求入参")
@Data
public class RuleGradeCreateRequestDTO extends BaseDTO {@Schema(description = "等级设置不能为空", required = true)@NotNull(message = "等级设置不能为空")private List<RuleGradeCreateDetailRequestDTO > detailRequestDTOList;@Schema(description = "等级数量不能为空", required = true)@NotNull(message = "等级数量不能为空")private Integer gradeNum;@Schema@Datapublic static class RuleGradeCreateDetailRequestDTO {@Schema(description = "等级设置不能为空", required = true)@NotNull(message = "等级设置不能为空")private String gradeName;@Schema(description = "得分率不能为空", required = true)@NotNull(message = "得分率不能为空")@Max(value = 100)@Min(value = 0)private Integer gradeRate;}
}出参
@Schema
@Data
public class GradeSearchResponseDTO extends BaseDTO {@Schema(description = "主键id", required = true)private String id;@Schema(description = "等级设置", required = true)private List<GradeSearchDetailResponseDTO> detailResponseDTOList;@Schema(description = "等级数量",required = true)private Integer gradeNum;@Datapublic static class GradeSearchDetailResponseDTO {@Schema(description = "等级名称", required = true)private String gradeName;@Schema(description = "得分率", required = true)private Integer gradeRate;}}三、添加配置文件
创建一个SwaggerConfig.java文件，用来配置生成哪些接口，这里我指定了生成/grade这个url下的所有接口
注意：SwaggerConfig文件中可以指定生成的api路径范围：可以扫描整个包，也可以针对某一个url进行生成，非常灵活，实际生产过程中开发人员自行指定生成的api范围，方便增量更新api接口
/*** @author huangtc* @description: 这个文件建议不要提交到线上环境，本地使用即可，如果非要通过git协作共享该文件，一定要设置.enable(false);* 这个文件建议不要提交到线上环境，本地使用即可，如果非要通过git协作共享该文件，一定要设置.enable(false);* 这个文件建议不要提交到线上环境，本地使用即可，如果非要通过git协作共享该文件，一定要设置.enable(false);* 这个文件建议不要提交到线上环境，本地使用即可，如果非要通过git协作共享该文件，一定要设置.enable(false);*/
@Configuration
@EnableOpenApi
public class SwaggerConfig {/*** 创建API*/@Beanpublic Docket createRestApi() {return new Docket(DocumentationType.OAS_30)// 用来创建该API的基本信息，展示在文档的页面中（自定义展示的信息）.apiInfo(apiInfo())// 设置哪些接口暴露给Swagger展示.select()// 扫描所有有注解的api，用这种方式更灵活// .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))// 扫描所有//.apis(RequestHandlerSelectors.any())// 指定扫描某个包//.apis(RequestHandlerSelectors.basePackage("com.huangtc.xxx.controller.GradeController"))// 扫描所有路径//.paths(PathSelectors.any())// 导出指定的url.paths(PathSelectors.ant("/huangtc/grade/**")).build()// 生产环境禁用，本地环境需要导出api的时候再设置.enable(true)// 这个文件建议不要提交到线上环境，本地使用即可// 如果非要通过git协作共享该文件，一定要设置.enable(false);.enable(true);}/*** 添加摘要信息*/private ApiInfo apiInfo() {// 用ApiInfoBuilder进行定制return new ApiInfoBuilder()// 设置标题.title("xxx系统_接口文档").description("xxx系统_接口文档描述").version("1.0").build();}
}四、导出接口
ui可视化访问地址：http://localhost:9060/项目请求路径/swagger-ui/index.html
api-docs访问地址：http://localhost:9060/项目请求路径/v3/api-docs
访问api-docs地址，将浏览器上的接口文本另存为txt文件，例如grade_api.txt，方便后续导入到YApi。
五、导入到YApi
打开yapi网页，依次点击 数据管理->数据导入选择Swagger->公共分类->数据同步按需选择->点击文件上传，选择刚刚创建的api.txt->点击确认
当然如果api-docs访问地址支持公网访问，则也可以点击“开启url导入”。
六、Swagger自动同步
首先确保api-docs访问地址支持公网访问，然后依次点击 设置->Swagger自动同步->选择如图所示
七、Swagger3.0对比Swagger2.0的注解变化
-
@ApiImplicitParam：在 Swagger 2.0 中用于描述单个请求参数详细信息，Swagger 3.0 中已经启用了 @Parameter 来取代 @ApiImplicitParam。
-
@ApiImplicitParams：在 Swagger 2.0 中被用来描述多个请求参数详细信息，Swagger 3.0 中已经不再使用。
-
@ApiModel：在 Swagger 2.0 中是用于描述数据模型的元素，Swagger 3.0 中已经废弃了，取而代之的是 @Schema。
-
@ApiModelPropery：在 Swagger 2.0 中是用于描述模型属性信息的注解，Swagger 3.0 中已经废弃了，取而代之的是@Schema。
-
@ApiError：在 Swagger 2.0 中用于描述错误响应信息，Swagger 3.0 中已经废弃了，取而代之的是 @ApiResponse。
-
@ApiIgnore：在 Swagger 2.0 中用于忽略某个 API 接口，Swagger 3.0 中已经废弃了，取而代之的是 @Operation(hidden=true)。
