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


    背景:使用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

  • 相关阅读:
    Codeforces_462_B
    Codeforces_460_B
    Codeforces_456_A
    2016.11.27
    Buy the Ticket{HDU1133}
    高精度模板
    盐水的故事[HDU1408]
    测试你是否和LTC水平一样高[HDU1407]
    完数[HDU1406]
    Air Raid[HDU1151]
  • 原文地址:https://www.cnblogs.com/xuxiaojian/p/14785291.html
Copyright © 2020-2023  润新知