Swagger API Spec + Swagger Codegen + YAPI管理接口文档

目录

• 1、项目接入Swagger
• 2、项目引入maven插件
• 3、编写Swagger API Spec（接口定义文档）
• 4、代码生成
  • 生成方式
  • 生成的目录结构
• 5、项目中加入Swagger配置文件

背景：使用SpringCloud进行微服务开发，且后端服务调用大都使用Feign Client进行调用。

1、项目接入Swagger

<dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.9.2</version>
        </dependency>
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>2.9.2</version>
        </dependency>

2、项目引入maven插件

<plugin>
                <groupId>io.swagger</groupId>
                <artifactId>swagger-codegen-maven-plugin</artifactId>
                <version>3.1.2</version>
                <configuration>
                    <!-- springcloud固定配置-start -->
                    <language>spring</language>
                    <library>spring-cloud</library>
                    <generateApis>true</generateApis>
                    <generateModels>true</generateModels>
                    <generateSupportingFiles>false</generateSupportingFiles>
                    <!-- springcloud固定配置-end -->
                    <additionalProperties>
                        <additionalPropertie>java8=true</additionalPropertie>
                        <additionalPropertie>generateForOpenFeign=true</additionalPropertie>
                        <!-- feign服务名称 -->
                        <additionalPropertie>title=myproject</additionalPropertie>
                    </additionalProperties>
                    <!-- swagger 接口定义文件位置 -->
                    <inputSpec>/Users/jarry/Downloads/swagger.yaml</inputSpec>
                    <!-- 生成的代码输出位置 -->
                    <output>${project.artifactId}</output>
                    <!-- api包路径 -->
                    <apiPackage>com.jarry.myproject.api</apiPackage>
                    <!-- model包路径 -->
                    <modelPackage>com.jarry.myproject.dto</modelPackage>
                </configuration>
            </plugin>

3、编写Swagger API Spec（接口定义文档）

参考：

swagger: '2.0'
info:
  title: myproject
  version: last
basePath: /feign
tags:
  - name: feign接口
schemes:
  - http
paths:
  /feign/user/foo:
    get:
      tags:
        - feign接口
      operationId: foo
      summary: ''
      description:
        0：成功
      parameters:
        - name: param
          in: query
          required: true
          description: 参数
          type: string
      responses:
        '200':
          description: successful operation
  /feign/user/bar:
    post:
      tags:
        - feign接口
      operationId: bar
      summary: ''
      description: ''
      consumes:
        - application/json
      parameters:
        - name: paramDTO
          in: body
          schema:
            type: object
            properties:
              param1:
                type: string
                description: ''
              param2:
                type: string
                description: ''
            required:
              - param1
              - param2
      responses:
        '200':
          description: successful operation
          schema:
            type: string

详细的编写规范参考：https://github.com/OAI/OpenAPI-Specification/blob/main/versions/2.0.md

4、代码生成

生成方式

方式一：

在IDEA插件列表双击执行

方式二：

通过命令

mvn io.swagger:swagger-codegen-maven-plugin:generate

执行

生成的目录结构

{output}/src/main/java/{apiPackage}和{output}/src/main/java/{modelPackage}

其中output是上面maven插件配置的输出目录，apiPackage是上面maven插件配置的api包路径，modelPackage是上面maven插件配置的model包路径

5、项目中加入Swagger配置文件

参考：

/**
 * @author xujian
 * 2021-04-21 17:41
 **/
@Configuration
@EnableSwagger2
public class SwaggerConfig {
    @Value("${swagger-ui.enable:false}")
    private Boolean enableSwaggerUI;
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .enable(enableSwaggerUI)
                .apiInfo(new ApiInfoBuilder()
                        .title("myproject")
                        .description("myproject接口文档")
                        .version("1.0.0")
                        .contact(new Contact("墨鱼","","moyu@bjarry.com"))
                        .license("The Jarry License")
                        .licenseUrl("http://www.jarry.com")
                        .build())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.jarry.myproject.controller"))
                .paths(PathSelectors.any())
                .build();
    }
}

6、访问Swagger UI
启动项目，访问http://ip:port/swagger-ui.html

复制图中红框里的链接

7、接口导入到YAPI

注意需要将localhost替换为真实ip