运用swagger编写api文档

Posted 2020-11-26 smile radiantly

一.什么是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.字段类型与格式定义

普通名字	type	format	说明
integer	integer	int32	签署了32位
long	integer	int64	签署了64位
float	number	float
double	number	double
string	string
byte	string	byte	base64编码的字符
binary	stirng	binary	任何的八位字节序列
boolean	boolean
date	string	date	所定义的full-date- - - - - -RFC3339
datetime	string	date-time	所定义的date-time- - - - - -RFC3339
password	stirng	password	用来提示用户界面输入需要模糊

四.示例-城市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文档了