基于yaml格式的swagger文档的编写（常应用于微服务中）

一. 引入maven依赖

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

二 .编写swagger-api.yml

swagger: "2.0"
info:
  title: "使用swagger-ui文档"
  description: "使用swagger-ui文档"
  version: "1.1.0"
basePath: "/test-service"
tags:
- name: "tag1"
- name: "tag2"
- name: "tag2"
schemes:
- "http"
paths:
  /test/queryUser:
    post:
      tags:
      - "tag1"
      summary: "查询用户（用于测试）"
      description: ""
      operationId: ""
      consumes:
      - "application/json"
      produces:
      - "application/json"
      parameters:
       - in: "query"
         name: "userName"
         type: string
         description: "用户名称"
         required: true
      responses:
        200:
          description:
          schema:
            $ref: "bean-definition.yml#/definitions/resultDto"
        400:
          description: Bad request
        401:
          description: Unauthorized
        403:
          description: Forbidden
        404:
          description: Not found
        500:
          description: Internal Server Error
  /test/modifyUser:
    post:
      tags:
      - "tag2"
      summary: "修改用户信息（用于测试）"
      description: ""
      operationId: ""
      consumes:
      - "application/json"
      produces:
      - "application/json"
      parameters:
        - in: "body"
          name: "body"
          description: "修改用户信息入参Json"
          required: true
          schema:
            $ref: "bean-definition.yml#/definitions/modifyParameter"
      responses:
        200:
          description:
          schema:
            $ref: "bean-definition.yml#/definitions/resultDto"
        400:
          description: Bad request
        401:
          description: Unauthorized
        403:
          description: Forbidden
        404:
          description: Not found
        500:
          description: Internal Server Error

三.编写bean-definition.yam文件

definitions:
  modifyParameter:
    type: "object"
    properties:
      userId:
        type: "string"
        description: "用户id"
        default: "testId"
      UserName:
        type: "string"
        description: "用户名称"
        default: "userName"
  
  ResultDto:
      type: "object"
      properties:
        code:
          type: "string"
          default: "000000"
        message:
          type: "string"
          default: "成功"
        data:
          type: "object"
 

四. 创建swagger配置类

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.context.annotation.Primary;
import springfox.documentation.swagger.web.InMemorySwaggerResourcesProvider;
import springfox.documentation.swagger.web.SwaggerResource;
import springfox.documentation.swagger.web.SwaggerResourcesProvider;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

import java.util.ArrayList;
import java.util.List;

@Configuration
@EnableSwagger2
public class SwaggerConfig {
    @Bean
    @Primary
    public SwaggerResourcesProvider swaggerResourcesProvider(InMemorySwaggerResourcesProvider defaultResourcesProvider) {
        return () -> {
            SwaggerResource resource = new SwaggerResource();
            resource.setName("swagger使用 API");
            resource.setSwaggerVersion("2.0");
            resource.setLocation("/swagger-api.yml");
            List<SwaggerResource> resourcesList = new ArrayList<>(defaultResourcesProvider.get());
            resourcesList.clear();
            resourcesList.add(0, resource);
            return resourcesList;
        };
    }

}

五. 注意事项

由于yaml格式的文本，采用缩进的方式进行层级的划分，故在编写时极其容易出现错误，下面推荐两个可以对yaml格式校验的网站便于排除在编写yaml格式的文件的错误。

yaml校验工具（使用上感觉上面的这个网址提示较完善）)
http://www.bejson.com/validators/yaml_editor/

editor.swagger.io/#