运用swagger编写api文档

一.什么是swagger

随着互联网技术的发展,前后端技术在各自的道路上越走越远,他们之间的唯一联系变成了api接口,api接口文档编程了前后端人员的纽带,而swagger就是书写api文档的一款框架.

官网: https://swagger.io/

相关资源下载地址: https://download.csdn.net/download/zhixingwu/12008773

推荐: 也可以使用 showdoc来书写api文档. 官网: https://www.showdoc.cc/

二.SwaggerEditor的安装与启动

1. 下载 swagger-editor.zip
2. 解压swagger-editor
3. 全局安装http-server(http-server是一个简单的零配置命令行http服务器)
   

   npm install ‐g http‐server

4. 启动swagger-editor
   

   http‐server swagger‐editor

5. 浏览器打开： http://localhost:8080
   

   三.语法规则

   1.固定字段

   字段名	类型	描述
   swagger	string	必需的。使用指定的规范版本
   info	info Object	必需的。提供元数据API
   host	string	主机名或ip服务API
   basePath	string	API的基本路径
   schemes	[string]	API的传输协议。 值必须从列表中:"http","https","ws","wss"。
   consumes	[string]	一个MIME类型的api可以使用列表。值必须是所描述的Mime类型
   produces	[string]	MIME类型的api可以产生的列表。 值必须是所描述的Mime类型
   paths	路径对象	必需的。可用的路径和操作的API
   definitions	定义对象	一个对象数据类型生产和使用操作
   parameters	参数定义对象	一个对象来保存参数,可以使用在操作。 这个属性不为所有操作定义全局参数。
   responses	反应定义对象	一个对象响应,可以跨操作使用。 这个属性不为所有操作定义全球响应
   externalDocs	外部文档对象	额外的外部文档
   summary	string	什么操作的一个简短的总结。 最大swagger-ui可读性,这一领域应小于120个字符
   description	string	解释操作的行为
   operationId	string	独特的字符串用于识别操作。 id必须是唯一的在所有业务中所描述的API。 工具和库可以使用operationId来唯一地标识一个操作,因此,建议遵循通用的编程的命名约定
   deprecated	boolean	声明该操作被弃用。 使用声明的操作应该没有。 默认值是false

2.字段类型与格式定义

四.示例-城市API文档

swagger: '2.0'
info:
  version: "1.0.0"
  title: 基础模块-城市API
host: api.pcloud.com
basePath: /base
paths:
  /city:
    post:
      summary: 新增城市
      parameters:
        -
          name: body
          in: body
          description: 城市实体类
          required: true
          schema:
            $ref: '#/definitions/City'
      responses:
        200:
          description: 成功响应
          schema:
            $ref: '#/definitions/ApiResponse'
    get:
      summary: 返回城市列表
      responses:
        200:
          description: 成功响应
          schema:
            $ref: '#/definitions/ApiCityListResponse'
  /city/{cityId}:
    put:
      summary: 修改城市
      parameters:
        - name: cityId
          in: path
          description: 城市ID
          required: true
          type: string
        - name: body
          in: body
          description: 城市实体类
          required: true
          schema:
            $ref: '#/definitions/City'
      responses:
        200:
          description: 成功响应
          schema:
            $ref: '#/definitions/ApiResponse'
    delete:
      summary: 根据ID删除城市
      parameters:
        - name: cityId
          in: path
          description: 城市ID
          required: true
          type: string
      responses:
        200:
          description: 成功响应
          schema:
            $ref: '#/definitions/ApiResponse'
    get:
      summary: 根据ID查询城市
      parameters:
        - name: cityId
          in: path
          description: 城市ID
          required: true
          type: string
      responses:
        200:
          description: 成功响应
          schema:
            $ref: '#/definitions/ApiCityResponse'
  /city/search:
    post:
      summary: 根据条件查询城市列表
      parameters:
        - name: body
          in: body
          description: 城市实体类
          required: true
          schema:
            $ref: '#/definitions/City'
      responses:
        200:
          description: 成功响应
          schema:
            $ref: '#/definitions/ApiCityListResponse'
  /city/search/{page}/{size}:
    post:
      summary: 城市分页列表
      parameters:
        - name: page
          in: path
          description: 页码
          required: true
          type: integer
          format: int32
        - name: size
          in: path
          description: 页大小
          required: true
          type: integer
          format: int32
        - name: body
          in: body
          description: 城市实体类
          required: true
          schema:
            $ref: '#/definitions/City'
      responses:
        200:
          description: 成功响应
          schema:
            $ref: '#/definitions/ApiCityPageResponse'
definitions:
  City:
    type: object
    properties:
      id:
        type: string
        description: ID
      name:
        type: string
        description: 城市名称
      ishot:
        type: string
        description: 是否热门
  ApiResponse:
    type: object
    properties:
      flag:
        type: boolean
        description: 是否成功
      code:
        type: integer
        format: int32
        description: 返回码
      message:
        type: string
        description: 返回信息
  ApiCityResponse:
    type: object
    properties:
      flag:
        type: boolean
        description: 是否成功
      code:
        type: integer
        format: int32
        description: 返回码
      message:
        type: string
        description: 返回信息
      data:
        $ref: '#/definitions/City'
  CityList:
    type: array
    items:
        $ref: '#/definitions/City'
  ApiCityListResponse:
    type: object
    properties:
      flag:
        type: boolean
        description: 是否成功
      code:
        type: integer
        format: int32
        description: 返回码
      message:
        type: string
        description: 返回信息
      data:
        $ref: '#/definitions/CityList'
  ApiCityPageResponse:
    type: object
    properties:
      flag:
        type: boolean
        description: 是否成功
      code:
        type: integer
        format: int32
        description: 返回码
      message:
        type: string
        description: 返回信息
      data:
        properties:
          total:
            type: integer
            format: int32
          rows:
            $ref: '#/definitions/CityList' 

五.批量生成API文档

使用<>自动生成所有标的yml文档,自动生成的文档中类型均为string ，我们这里需要再对类型进行修改即可.
步骤：
（1）执行建表脚本
（2）使用《黑马程序员代码生成器》生成脚本(HeimaCodeUtil_V2.4_64.zip)

六.swaggerUI

SwaggerUI是用来展示Swagger文档的界面，以下为安装步骤
（1）在本地安装nginx
（2）下载SwaggerUI源码 https://swagger.io/download-swagger-ui/
（3）解压，将dist文件夹下的全部文件拷贝至 nginx的html目录
（4）启动nginx
（5）浏览器打开页面 http://localhost即可看到文档页面
（6）将编写好的yml文件也拷贝至nginx的html目录，这样我们就可以加载我们的swagger文档了

原文地址：https://www.cnblogs.com/itzlg/p/11966754.html