Swagger3.0接口生成并导入YApi

hungteshun

于 2024-06-18 18:12:38 发布

阅读量601

点赞数 24

文章标签： swagger swagger3.0

本文链接：https://blog.csdn.net/hjfcgt123/article/details/139779452

版权

一、引入依赖

    <!--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 {

    @Autowired
    private 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
    @Data
    public 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;

    @Data
    public 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
     */
    @Bean
    public 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)。