Swagger Editor 的介绍和使用

Swagger Editor 可以帮助开发人员优雅地设计符合 OpenAPI 规范的API接口，是一个可以通过浏览器进行使用的工具。功能如下：

• 编辑：可以在浏览器上基于YAML等语法定义我们的RESTful API，也可以采用 JSON语法

• 查看：Swagger Editor会自动生成一篇排版优美的API文档，并且提供实时预览

• 生成代码：可智能生成服务端或客户端代码，支持 python、golang、java 等主流语言

安装

参见： swagger-editor/README.md at master · swagger-api/swagger-editor · GitHub 

编写文档

参见： OpenAPI Specification - Version 3.0.3 | Swagger

我们如果把一个OpenAPI文档 当成一个对象，那么 OpenAPI Object 包括 openapi、info、jsonSchemaDialect、servers、paths 等10个字段。

下面，依次讲解常用的几个字段：

扫描二维码关注公众号，回复： 15449353 查看本文章

# 这part为整个OpenAPI文档的metadata部分
openapi: 3.0.0  # 用于指定当前配置文件基于哪个版本
info:           # 用于描述当前的基本信息 
  title: ""
  description: ""
  version: ""

# 这part定义了一个可以访问的server列表，用于api的测试
servers:
  - url:
    description:

# 这part用于定义实际的每个api, 示例如下：
paths:
  /users:
    get:
      summary: Returns a list of users.
      description: Optional extended description in CommonMark or HTML.
      responses:
        '200':    # status code
          description: A JSON array of user names
          content:
            application/json:
              schema: 
                type: array
                items: 
                  type: string

# components这部分用于定义可以复用的数据结构，示例如下：
components:
  schemas:
    User:
      type: object
      properties:
        id:
          type: integer
          example: 4
        name:
          type: string
          example: Arthur Dent
      # Both properties are required
      required:  
        - id
        - name
paths:
  /users/{userId}:
    get:
      summary: Returns a user by ID.
      parameters:
        - in: path
          name: userId
          required: true
          schema:
            type: integer
            format: int64
            minimum: 1
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'    # <-------
  /users:
    post:
      summary: Creates a new user.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/User'      # <-------
      responses:
        '201':
          description: Created