swagger描述restful接口

项目交付的时候客户要求提供基于swagger的restful接口文档，所以简单使用了一下。

Swagger

Swagger是规范restful api服务的工具，可以用来定义接口和测试接口。
Swagger的核心工具有三个：

• Swagger-UI：API展示和测试页面
• Swagger-Editor：所见即所得式编辑工具
• Swagger-Codegen: 利用代码直接生成规范文档的工具

使用Swagger来约定接口有两种方式：

1. 在编辑器中写好文档，用yaml来表述，然后用Swagger-ui来展示
2. 在后端代码中按照约定方式写上注释，然后使用Swagger-codegen自动扫描生成。

这里只简单介绍第一种方式

1. 新建一个项目，运行npm init初始化，并创建public目录
2. 下载Swagger-ui将dist目录下的文件复制到public下
3. public下新建swagger.yaml文件，打开https://editor.swagger.io/把编辑器中的yaml内容复制过来
4. 把public/index.html中的url改为'./swagger.yaml'
5. 简单创建一个node服务，在项目目录下创建app.js

// 先安装依赖的express，opn包
var express = require('express');
var app = express(); 
var opn = require('opn'); 

app.listen(3000, function () { 
  opn('http://localhost:3000/api-doc');
  console.log('App listening on port 3000!');
});

app.use('/api-doc', express.static('public'));

6. 运行服务node app.js即可打开界面

image.png

7. 修改swagger.yaml文件即可

编辑文档中的字段含义如下

swagger: '2.0'                      # swagger的版本
info:
  title: 文档标题
  description:  描述
  version: "v1.0"                   # 版本号
  termsOfService: ""                # 文档支持截止日期
  contact:                          # 联系人的信息
    name: ""                        # 联系人姓名
    url: ""                         # 联系人URL
    email: ""                       # 联系人邮箱
  license:                          # 授权信息
    name: ""                        # 授权名称，例如Apache 2.0
    url: ""                         # 授权URL
host: api.haofly.net                # 域名，可以包含端口，如果不提供host，那么默认为提供yaml文件的host
basePath: /                         # 前缀，比如/v1
schemes:                            # 传输协议
  - http
  - https

securityDefinitions:                # 安全设置
  api_key:
    type: apiKey
    name: Authorization             # 实际的变量名比如，Authorization
    in: header                      # 认证变量放在哪里，query或者header
  OauthSecurity:                    # oauth2的话有些参数必须写全
    type: oauth2
    flow: accessCode                # 可选值为implicit/password/application/accessCode
    authorizationUrl: 'https://oauth.simple.api/authorization'
    tokenUrl: 'https://oauth.simple.api/token'
    scopes:
      admin: Admin scope
      user: User scope
      media: Media scope
  auth:
    type: oauth2
    description: ""                 # 描述
    authorizationUrl: http://haofly.net/api/oauth/
    name: Authorization             # 实际的变量名比如，Authorization
    tokenUrl:
    flow: implicit                  # oauth2认证的几种形式，implicit/password/application/accessCode
    scopes:
      write:post: 修改文件
      read:post: 读取文章

security:                           # 全局的安全设置的一个选择吧
  auth:
    - write:pets
    - read:pets

consumes:                           # 接收的MIME types列表
  - application/json                # 接收响应的Content-Type
  - application/vnd.github.v3+json

produces:                           # 请求的MIME types列表
  - application/vnd.knight.v1+json  # 请求头的Accept值
  - text/plain; charset=utf-8
tags:                               # 相当于一个分类
  - name: post  
    description: 关于post的接口

externalDocs:
  description: find more info here
  url: https://haofly.net

paths:                              # 定义接口的url的详细信息
  /projects/{projectName}:          # 接口后缀，可以定义参数
    get:
      tags:                         # 所属分类的列表
        - post  
      summary: 接口描述              # 简介
      description:                  # 详细介绍
      externalDocs:                 # 这里也可以加这个
        description:
        url:
      operationId: ""               # 操作的唯一ID
      consumes: [string]            # 可接收的mime type列表
      produces: [string]            # 可发送的mime type列表
      schemes: [string]             # 可接收的协议列表
      deprecated: false             # 该接口是否已经弃用
      security:                     # OAuth2认证用
        - auth: 
            - write:post
            - read: read
      parameters:                   # 接口的参数
        - name: projectName         # 参数名
          in: path                  # 该参数应该在哪个地方，例如path、body、query等，但是需要注意的是如果in body，只能用schema来指向一个定义好的object，而不能直接在这里定义
          type: string              # 参数类型
          allowEmptyValue: boolean          # 是否允许为空值
          description: 项目名        # 参数描述
          required: true            # 是否必须
          default: *                # 设置默认值
          maximum: number           # number的最大值
          exclusiveMaximum: boolean # 是否排除最大的那个值
          minimum: number           # number的最小值
          exclusiveMinimum: boolean
          maxLength: integer        # int的最大值
          minLength: integer
          enum: [*]                 # 枚举值
          items:                    # type为数组的时候可以定义其项目的类型
        - $ref: "#/parameters/uuidParam"   # 这样可以直接用定义好的
      responses:                    # 设置响应
        200:                        # 通过http状态来描述响应
          description: Success      # 该响应的描述
          schema:                   # 定义返回数据的结构
            $ref: '#/definitions/ProjectDataResponse'  # 直接关联至某个model

  /another: # 另一个接口
      responses:
        200:
            description:
            schema:
              type: object
              properitis:
                data:
                    $ref: '#/definitions/User' # 关联

definitions:            # Model/Response的定义，这里的定义不强制要求返回数据必须和这个一致，但是在swagger-ui上，会展示这里面的字段。
  Product:              # 定义一个model
    type: object        # model类型
    properties:         # 字段列表
      product_id:       # 字段名
        type: integer   # 字段类型
        description:    # 字段描述
      product_name:
        type: string
        description: 
  ProjectDataResponse:
    type: object
    properties:
        data:
            $ref: '#/definitions/ProjectResponse'  # model之间的关联，表示在data字段里面包含的是一个ProjectResponse对象
parameters:             # 可以供很多接口使用的params
  limitParam:
    name: limit
    in: query
    description: max records to return
    required: true
    type: integer
    format: int32
responses:              # 可以供很多接口使用的responses
  NotFound:
    description: Entity not found.

参考链接
https://blog.csdn.net/rth362147773/article/details/78992043
https://zhuanlan.zhihu.com/p/26741562