Swagger Editor 的部署使用

一、swagger 本地部署

Swagger Editor 可以使用在线编辑器，也可以离线本地部署环境。使用YAML定义接口规范，接口文档生成不同框架服务端、客户端。可以导出JSON格式API规范，通过Swagger UI发布。

1、安装 nodejs、npm

npm是Nodejs的包管理器

戳node.js官网

戳node.js文档

2、npm 安装 http server

npm install -g http-server

..\npm\下生成http-server、hs

..\npm\node_modules下生成http-server

3、下载项目

Swagger-Editor GitHub项目

4、环境变量

拷贝hs.cmd的绝对路径C:\Users\Administrator\AppData\Roaming\npm（npm安装hs的目录）作为HS_HOME环境变量

5、运行hs服务

命令行 cd 到 Swagger-Editor 项目下载存放目录，运行命令 hs ，默认端口8080；也可指定端口 hs -p 8081；Ctrl+C 可以停止服务运行

二、Swagger 使用

• 建议使用Firefox/Google Chrome访问 http://127.0.0.1:8080

• YAML格式字段，附：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.xxx.net                   # 域名，可包含端口，默认提供yaml文件的host
  basePath: /                         # 前缀
  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                  # 认证形式，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等
            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的定义
    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.
  

三、关于

博主CSDN@崔同学原创码字不易，喜欢记得点赞收藏支持哦