前言

现在，在程序开发中前后端分离的模式已经成了主流，而在前后端分离的项目中，如果后端的开发人员能提供一份清晰明了的接口文档，那么对接的前端开发人员也会轻松很多，大大的提高了前后端沟通效率和开发速度

Swagger可以用来定义和记录RESTful Web服务的接口文档，可以通过使用给接口代码添加申明式注释的方式、也可以使用yml文档格式来生成swagger渲染的前端接口文档界面

下面来介绍第二种：使用yml文档格式的方式来生成swagger渲染接口文档，用的是OpenAPI 3的标准

yml文档规则

openapi: 3.0.0 #必填字段 指定swagger版本号
info:
  description: 接口文档的总描述#接口文档描述
  version: "1.1.0" #文档版本
  title: test 服务 #接口文档标题
  contact:
    email: xxx@xxx.com #联系邮箱
servers:
  - description: 这是接口文档的IP端口地址 #地址的描述
    url: http://127.0.0.1:8080/ #接口的IP端口地址
tags:
  - name: 服务接口组1
    description: 这是接口组1的注释 #给下面有相应标签的接口添加注释
  - name: 用户
    description: 这是接口用户组的注释

paths: 
  /service-test/v1/login:
    post: #必填字段,定义HTTP操作方法，必须是http协议定义的方法
      tags:
        - 用户 #能通过上面tag desc添加标签注释
      summary: 用户登录 #接口描述
      parameters: #参数
        - name: SECRET_CODE
          in: header #参数参数的地方，可填header、path、query
          description: 用户鉴权码
          required: true #是否必填
          schema:
            type: string #参数类型 可选的类型还有array、object、integer、string、boolean
      requestBody: #请求结构体(如果有才写)
        content:
          application/json: #指定类型为json格式
            schema:
              type: object 
              example: #给出例子
                {
                  "phone":"12345678910",
                  "password":"123456"
                }
      responses: #返回值(必要)
        '200': #返回成功
          description: successful operation
          content:
            application/json:
              schema:
                type: object
                example:
                  {
                    "code":20000,
                    "msg":"user login success",
                    "token":"qwertyuiop"
                  }
        '404': #返回404失败
          description: page not found

另一种参数方式

paths:
  /service-test/v1/get_self_info:
    get:
      tags:
        - 用户
      summary: 获取用户个人信息
      parameters:
        - name: token
          in: header
          description: token
          required: true
          schema:
            type: string
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Info' #引用在definitions下定义的Info
        'default': #执行出错的处理
          description: 请求失败
        
components:
  schemas:
    Info:
      type: object  #值类型
      properties: #定义属性
        id: #属性名
          type: integer
          format: int64
        username:
          type: string
        age:
          type: integer
          format: int64