Swagger学习

绝地灬酷狼 2023-06-17 08:59 47阅读 0赞

官方下载地址：[swagger官方下载地址][swagger]

> swagger是一款让你更好的书写API文档的框架。

# Swagger Editor #

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

npm install ‐g http‐server

（4）启动swagger-editor 启动时，CMD位置必须在swagger-editor文件夹的父目录中，如下：  
![在这里插入图片描述][20191128134324929.png]

http‐server swagger‐editor

（5）浏览器打开： [http://localhost:8080][http_localhost_8080]  
![在这里插入图片描述][watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3poaXpoZW5nZ3Vhbg_size_16_color_FFFFFF_t_70]

# Swagger语法规则 #

## 字段类型与格式定义 ##

![在这里插入图片描述][watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3poaXpoZW5nZ3Vhbg_size_16_color_FFFFFF_t_70 1]

## 固定字段 ##

<table> 
 <thead> 
  <tr> 
   <th>字段名</th> 
   <th>类型</th> 
   <th>描述</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td>swagger</td> 
   <td>string</td> 
   <td>必需的。使用指定的规范版本。</td> 
  </tr> 
  <tr> 
   <td>infoInfo</td> 
   <td>Object</td> 
   <td>必需的。提供元数据API。 可以使用元数据的客户如果需要。</td> 
  </tr> 
  <tr> 
   <td>host</td> 
   <td>string</td> 
   <td>主机名或ip服务API。</td> 
  </tr> 
  <tr> 
   <td>basePath</td> 
   <td>string</td> 
   <td>API的基本路径,这是相对的host。 如果不包括,API是直属host。 必须从价值领先斜杠(/)。 的basePath不支持路径模板。</td> 
  </tr> 
  <tr> 
   <td>schemes</td> 
   <td>[string]</td> 
   <td>API的传输协议。 值必须从列表中:“http”,“https”,“ws”,“wss”。 如果schemes不包括,默认使用计划是用于访问大摇大摆的定义本身。</td> 
  </tr> 
  <tr> 
   <td>consumes</td> 
   <td>[string]</td> 
   <td>一个MIME类型的api可以使用列表。 这是可以覆盖全球所有API,但在特定的API调用。 值必须是所描述的Mime类型。</td> 
  </tr> 
  <tr> 
   <td></td> 
   <td></td> 
   <td></td> 
  </tr> 
  <tr> 
   <td></td> 
   <td></td> 
   <td></td> 
  </tr> 
 </tbody> 
</table>

# 基础模块API #

## 城市API ##

swagger: "2.0"
    info:
      description: "城市"
      version: "1.0.0"
      title: "Swagger Petstore"
    host: "petstore.swagger.io"
    basePath: "/api"
    schemes:
    - "http"
    paths:
      '/city':
        post:
          summary: "增加城市"
          description: "增加城市，返回是否成功"
          operationId: "addCity"
          consumes:
          - "application/json"
          produces:
          - "application/json"
          parameters:
          - in: "body"
            name: "body"
            description: ""
            required: true
            schema:
              $ref: "#/definitions/City"
          responses:
            200:
              description: successful operation
              schema:
                $ref: '#/definitions/ApiResponse'
            405:
              description: "Invalid input"
    definitions:
      City:
        type: "object"
        properties:
          id:
            type: "string"
            description: "ID"
          name:
            type: "string"
            description: "城市名称"
          ishot:
            type: "string"
            description: "是否热门"
        xml:
          name: "City"
      ApiResponse:
        type: "object"
        properties:
          code:
            type: "integer"
            format: "int32"
          flag:
            type: "boolean"
          message:
            type: "string"

![在这里插入图片描述][watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3poaXpoZW5nZ3Vhbg_size_16_color_FFFFFF_t_70 2]  
![在这里插入图片描述][watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3poaXpoZW5nZ3Vhbg_size_16_color_FFFFFF_t_70 3]

## 返回城市列表 ##

（1）在definitions下定义城市列表对象以及相应对象

CityList:
        type: "array"
        items: 
          $ref: '#/definitions/City'
      ApiCityListResponse:
        type: "object"
        properties:
          code:
            type: "integer"
            format: "int32"
          flag:
            type: "boolean"
          message:
            type: "string"
          data:
            $ref: '#/definitions/CityList'

（2）在/city增加get

get:
          summary: "城市全部列表"
          description: "返回城市全部列表"
          operationId: "findCityList"
          produces:
          - "application/json"
          responses:
            200:
              description: "成功查询到数据"
              schema: 
                $ref: '#/definitions/ApiCityListResponse'
            405:
              description: "Invalid input"

![在这里插入图片描述][watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3poaXpoZW5nZ3Vhbg_size_16_color_FFFFFF_t_70 4]

## 根据ID查询城市 ##

（1）在definitions下定义城市对象的响应对象

ApiCityResponse:
        type: "object"
        properties:
          code:
            type: "integer"
            format: "int32"
          flag:
            type: "boolean"
          message:
            type: "string"
          data:
            $ref: '#/definitions/City'

（2）新增/city/\{cityId\} ，设置get方法API

'/city/{cityId}':
        get:
          summary: 根据ID查询
          description: 返回一个城市
          operationId: getCityById
          produces:
            - application/json
          parameters:
            - name: cityId
              in: path
              description: 城市ID
              required: true
              type: integer
              format: int64
          responses:
            '200':
              description: 操作成功
              schema:
                $ref: '#/definitions/City'
            '404':
              description: 没找到城市

![在这里插入图片描述][watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3poaXpoZW5nZ3Vhbg_size_16_color_FFFFFF_t_70 5]

## 修改城市 ##

/city/\{cityId\} 下增加put

put:
          summary: "修改城市"
          description: "修改城市，返回是否成功"
          operationId: "updateCity"
          consumes:
          - "application/json"
          produces:
          - "application/json"
          parameters:
            - name: cityId
              in: path
              description: 城市ID
              required: true
              type: integer
              format: int64
            - name: "body"
              in: "body"
              description: ""
              required: true
              schema:
                $ref: "#/definitions/City"
          responses:
            200:
              description: "修改成功"
              schema:
                $ref: '#/definitions/ApiResponse'
            405:
              description: "输入无效"

![在这里插入图片描述][watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3poaXpoZW5nZ3Vhbg_size_16_color_FFFFFF_t_70 6]

## 删除城市 ##

/city/\{cityId\} 下增加delete

delete:
          summary: 根据ID删除
          description: 返回是否成功
          operationId: deleteCityById
          produces:
            - application/json
          parameters:
            - name: cityId
              in: path
              description: 城市ID
              required: true
              type: integer
              format: int64
          responses:
            '200':
              description: 操作成功
              schema:
                $ref: '#/definitions/ApiResponse'
            '404':
              description: 没找到城市

![在这里插入图片描述][watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3poaXpoZW5nZ3Vhbg_size_16_color_FFFFFF_t_70 7]

## 城市分页列表 ##

（1）在definitions下定义城市分页列表响应对象

ApiCityPageResponse:
        type: "object"
        properties:
          code:
            type: "integer"
            format: "int32"
          flag:
            type: "boolean"
          message:
            type: "string"
          data:
            properties:
              total:
                type: "integer"
                format: "int32"
              rows:
                $ref: '#/definitions/CityList'

（2）新增节点

'/city/search/{
        page}/{
        size}':
        post:
          summary: "城市分页"
          description: "显示城市分页数据"
          operationId: "cityPage"
          consumes:
          - "application/json"
          produces:
          - "application/json"
          parameters:
            - name: page
              in: path
              description: 页码
              required: true
              type: integer
              format: int64
            - name: size
              in: path
              description: "页码"
              required: true
              type: integer
              format: int64
            - name: "body"
              in: "body"
              description: "查询条件"
              required: true
              schema:
                $ref: "#/definitions/City"
          responses:
            200:
              description: 查询成功
              schema:
                $ref: '#/definitions/ApiCityPageResponse'
            405:
              description: "Invalid input"

最终完整的Swagger文档如下：

swagger: "2.0"
    info:
      description: "城市"
      version: "1.0.0"
      title: "十次方API列表-城市"
    host: "petstore.swagger.io"
    basePath: "/api"
    schemes:
    - "http"
    paths:
      '/city':
        post:
          summary: "增加城市"
          description: "增加城市，返回是否成功"
          operationId: "addCity"
          consumes:
          - "application/json"
          produces:
          - "application/json"
          parameters:
          - in: "body"
            name: "body"
            description: ""
            required: true
            schema:
              $ref: "#/definitions/City"
          responses:
            200:
              description: successful operation
              schema:
                $ref: '#/definitions/ApiResponse'
            405:
              description: "Invalid input"
        get:
          summary: "城市全部列表"
          description: "返回城市全部列表"
          operationId: "findCityList"
          produces:
          - "application/json"
          responses:
            200:
              description: "成功查询到数据"
              schema: 
                $ref: '#/definitions/ApiCityListResponse'
            405:
              description: "Invalid input"
      '/city/{
        cityId}':
        get:
          summary: 根据ID查询
          description: 返回一个城市
          operationId: getCityById
          produces:
            - application/json
          parameters:
            - name: cityId
              in: path
              description: 城市ID
              required: true
              type: integer
              format: int64
          responses:
            '200':
              description: 操作成功
              schema:
                $ref: '#/definitions/ApiCityResponse'
            '404':
              description: 没找到城市
        put:
          summary: "修改城市"
          description: "修改城市，返回是否成功"
          operationId: "updateCity"
          consumes:
          - "application/json"
          produces:
          - "application/json"
          parameters:
            - name: cityId
              in: path
              description: 城市ID
              required: true
              type: integer
              format: int64
            - name: "body"
              in: "body"
              description: ""
              required: true
              schema:
                $ref: "#/definitions/City"
          responses:
            200:
              description: "修改成功"
              schema:
                $ref: '#/definitions/ApiResponse'
            405:
              description: "输入无效"
        delete:
          summary: 根据ID删除
          description: 返回是否成功
          operationId: deleteCityById
          produces:
            - application/json
          parameters:
            - name: cityId
              in: path
              description: 城市ID
              required: true
              type: integer
              format: int64
          responses:
            '200':
              description: 操作成功
              schema:
                $ref: '#/definitions/ApiResponse'
            '404':
              description: 没找到城市
      '/city/search/{
        page}/{
        size}':
        post:
          summary: "城市分页"
          description: "显示城市分页数据"
          operationId: "cityPage"
          consumes:
          - "application/json"
          produces:
          - "application/json"
          parameters:
            - name: page
              in: path
              description: 页码
              required: true
              type: integer
              format: int64
            - name: size
              in: path
              description: "页码"
              required: true
              type: integer
              format: int64
            - name: "body"
              in: "body"
              description: "查询条件"
              required: true
              schema:
                $ref: "#/definitions/City"
          responses:
            200:
              description: 查询成功
              schema:
                $ref: '#/definitions/ApiCityPageResponse'
            405:
              description: "Invalid input"
    definitions:
      City:
        type: "object"
        properties:
          id:
            type: "string"
            description: "ID"
          name:
            type: "string"
            description: "城市名称"
          ishot:
            type: "string"
            description: "是否热门"
        xml:
          name: "City"
      CityList:
        type: "array"
        items: 
          $ref: '#/definitions/City'
      ApiResponse:
        type: "object"
        properties:
          code:
            type: "integer"
            format: "int32"
          flag:
            type: "boolean"
          message:
            type: "string"
      ApiCityResponse:
        type: "object"
        properties:
          code:
            type: "integer"
            format: "int32"
          flag:
            type: "boolean"
          message:
            type: "string"
          data:
            $ref: '#/definitions/City'
      ApiCityListResponse:
        type: "object"
        properties:
          code:
            type: "integer"
            format: "int32"
          flag:
            type: "boolean"
          message:
            type: "string"
          data:
            $ref: '#/definitions/CityList'
      ApiCityPageResponse:
        type: "object"
        properties:
          code:
            type: "integer"
            format: "int64"
          flag:
            type: "boolean"
          message:
            type: "string"
          data:
            properties:
              total:
                type: "integer"
                format: "int32"
              rows:
                $ref: '#/definitions/CityList'

[swagger]: https://github.com/swagger-api
[20191128134324929.png]: https://img-blog.csdnimg.cn/20191128134324929.png
[http_localhost_8080]: http://localhost:8080/
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3poaXpoZW5nZ3Vhbg_size_16_color_FFFFFF_t_70]: https://img-blog.csdnimg.cn/20191128134805988.png?x-oss-process=image/watermark,type_ZmFuZ3poZW5naGVpdGk,shadow_10,text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3poaXpoZW5nZ3Vhbg==,size_16,color_FFFFFF,t_70
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3poaXpoZW5nZ3Vhbg_size_16_color_FFFFFF_t_70 1]: https://img-blog.csdnimg.cn/20191128134849362.png?x-oss-process=image/watermark,type_ZmFuZ3poZW5naGVpdGk,shadow_10,text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3poaXpoZW5nZ3Vhbg==,size_16,color_FFFFFF,t_70
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3poaXpoZW5nZ3Vhbg_size_16_color_FFFFFF_t_70 2]: https://img-blog.csdnimg.cn/2019112814070339.png?x-oss-process=image/watermark,type_ZmFuZ3poZW5naGVpdGk,shadow_10,text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3poaXpoZW5nZ3Vhbg==,size_16,color_FFFFFF,t_70
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3poaXpoZW5nZ3Vhbg_size_16_color_FFFFFF_t_70 3]: https://img-blog.csdnimg.cn/20191128140714322.png?x-oss-process=image/watermark,type_ZmFuZ3poZW5naGVpdGk,shadow_10,text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3poaXpoZW5nZ3Vhbg==,size_16,color_FFFFFF,t_70
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3poaXpoZW5nZ3Vhbg_size_16_color_FFFFFF_t_70 4]: https://img-blog.csdnimg.cn/2019112814204060.png?x-oss-process=image/watermark,type_ZmFuZ3poZW5naGVpdGk,shadow_10,text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3poaXpoZW5nZ3Vhbg==,size_16,color_FFFFFF,t_70
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3poaXpoZW5nZ3Vhbg_size_16_color_FFFFFF_t_70 5]: https://img-blog.csdnimg.cn/20191128142230845.png?x-oss-process=image/watermark,type_ZmFuZ3poZW5naGVpdGk,shadow_10,text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3poaXpoZW5nZ3Vhbg==,size_16,color_FFFFFF,t_70
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3poaXpoZW5nZ3Vhbg_size_16_color_FFFFFF_t_70 6]: https://img-blog.csdnimg.cn/20191128142707352.png?x-oss-process=image/watermark,type_ZmFuZ3poZW5naGVpdGk,shadow_10,text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3poaXpoZW5nZ3Vhbg==,size_16,color_FFFFFF,t_70
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3poaXpoZW5nZ3Vhbg_size_16_color_FFFFFF_t_70 7]: https://img-blog.csdnimg.cn/20191128142802168.png?x-oss-process=image/watermark,type_ZmFuZ3poZW5naGVpdGk,shadow_10,text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3poaXpoZW5nZ3Vhbg==,size_16,color_FFFFFF,t_70