Vue项目中使用Swagger生成接口文档

参考“swagger配置和注释生成文档”：node从入门到放弃系列之（8）koa2 swaggerUI的使用_高素质车间工人的博客-CSDN博客_koa2 swagger

在线：Swagger Editor

下载：GitHub - swagger-api/swagger-ui: Swagger UI is a collection of HTML, JavaScript, and CSS assets that dynamically generate beautiful documentation from a Swagger-compliant API.

解压后，复制整个dist文件夹到服务端的public目录下，并改名为apidocs（随意）

在Swagger Editor中把文档保存为YAML或者JSON，我命名为swagger.json(或者swagger.yaml)

然后将文档放进api-docs文件夹，打开api-docs文件夹中的index.html，找到末尾的JavaScript，将url从http://petstore.swagger.io/v2/swagger.json修改为你的文档地址

启动你的项目，访问：http://localhost:3000/apidocs/index.html，文档就出现了！

注意：这个3000是服务端的端口

安装swagger-editor

https://github.com/swagger-api/swagger-editor

解压出来内容如下：

全局安装http-server

cnpm i -g http-server

进入swagger-editor目录，执行命令：http-server，打开展示的链接 

基础版：

swagger: '2.0'

info:
  version: 1.0.0
  title: 标题
  description: 描述：这是一个接口文档

paths: {}

type类型：

post

swagger: '2.0'
info:
  description: 描述：这是一个接口文档
  version: 1.0.0
  title: 接口文档
tags:
  - name: user
    description: 关于用户的操作
paths:
  /user:
    post:
      tags:
        - user
      summary: 创建用户
      description: 用户注册、或者管理员创建用户
      parameters:
        - in: body
          name: body
          description: 创建的用户对象
          required: true
          schema:
            $ref: '#/definitions/User'
      responses:
        200:
          description: 响应成功
          schema:
            type: object
            properties:
              id:
                type: integer
                format: int64
              username:
                type: string
                description: 用户名
              password:
                type: string
                description: 密码
              userStatus:
                type: boolean
                default: true
              sex:
                type: string
                description: 性别。枚举[man,woman]
                enum:
                  - man
                  - woman
              like: 
                type: array
                items: 
                  type: string
              tags: 
                type: array
                items: 
                  type: object
                  properties:
                    id:
                      type: integer
                      format: int64
                    name:
                      type: string
        404:
          description: 创建失败 
        default:
          description: 相应成功的操作
        
  
definitions:
  User:
    type: object
    required:
      - username
      - password
    properties:
      id:
        type: integer
        format: int64
      username:
        type: string
        description: 用户名
      password:
        type: string
      userStatus:
        type: boolean
        default: true
      
  

get

swagger: '2.0'
info:
  description: 描述：这是一个接口文档
  version: 1.0.0
  title: 接口文档
tags:
  - name: user
    description: 关于用户的操作
paths:
  /user/login:
    get:
      tags:
        - user
      summary: 用户登录
      description: 用户登录的接口
      parameters:
        - in: query
          name: username
          description: 用户名
          required: true
          type: string
        - in: query
          name: password
          description: 密码
          type: string
      responses:
        200:
          description: 响应成功

put / delete

url含有参数的情况，如下：

swagger: '2.0'
info:
  description: 描述：这是一个接口文档
  version: 1.0.0
  title: 接口文档
tags:
  - name: user
    description: 关于用户的操作
paths:
  /user/{username}:
    put:
      tags:
        - user
      summary: 修改用户
      description: ''
      parameters:
        - in: path
          name: username
          description: '用户名'
          required: true
          type: string
        - in: body
          name: body
          description: 要编辑的果树信息
          required: true
          schema:
            type: object
            properties:
              username:
                type: string
                description: 用户名
              password:
                type: string
              userStatus:
                type: integer
                format: int32
      responses:
        200:
          description: 修改用户成功
        404:
          description: 未找到用户
    delete:
      tags:
        - user
      summary: 根据用户名删除用户
      description: 只有管理员能删除用户
      parameters:
        - in: path
          name: username
          description: 根据用户名删除用户
          required: true
          type: string
      responses:
        200:
          description: 删除用户成功
        404:
          description: 删除失败
      deprecated: true