Swagger Editor教程

最新推荐文章于 2026-05-21 07:20:17 发布

原创最新推荐文章于 2026-05-21 07:20:17 发布 · 2.4w 阅读

62 ·

本内容遵循CC 4.0 BY-SA版权协议

标签

#swagger editor

swagger 专栏收录该内容

1 篇文章

订阅专栏

Swagger Editor是一个强大的API设计工具，支持Windows平台安装。它提供了交互式文档、代码生成SDK和API发现功能。安装过程包括安装Node.js和npm，下载Swagger Editor源码并启动服务。使用Swagger Editor编写YAML格式的API文档，可享受语法高亮、自动补全和实时预览等优势。通过示例展示了如何声明API规范、定义操作、响应类型和请求参数，以及如何处理body参数和引用定义。

Swagger是一个简单但功能强大的API表达工具，是目前现有的最大API工具生态系统。使用Swagger生成API，我们可以得到交互式文档，自动生成代码的SDK以及API的发现特性等。

安装

Windows上的安装

1、首先需要安装node和npm。你可以在cmd命令行看到你的安装信息。使用命令node -v和npm -v，可以用来查看版本信息。
2、安装后，还需要安装http-server。使用命令npm install -g http-server。
3、接着去Swagger Editor官网下载源码。
在这里插入图片描述
4、下载完成后，从命令行中进入http-server的安装目录，也就是npm包下载的位置。

5、最后将swagger editor服务启动起来

上面红色标记的是Swagger Editor压缩包解压后的位置。启动成功后，在浏览器中输入127.0.0.1:8081就可以看到下面的界面。
在这里插入图片描述

使用

我们可以选择使用JSON或者YAML的语言格式来编写API文档，但是建议用YAML来写，因为它更简单。编写API文档，我们只是在写一个简单的文本文件。我们可以使用任何文档编辑器来写，但是为了提高效率，建议使用专业的编辑工具。众多工具中，最好的选择就是Swagger Editor。它能提供语法高亮、自动补全、及时预览等功能。

例子

swagger: '2.0'

info:
  version: 1.0.0
  title: Simple API
  description: A simple API to learn how to write OpenAPI Specification

schemes: 
  - https
host: simple.api
basePath: /openapi01

paths: {}

第一行通过swagger属性来声明OpenAPI规范的版本，OpenAPI规范是基于Swagger的，目前这个属性的值只能是2.0.接着是API的描述信息，用info属性。
接着是API的URL，使用的协议，主机名、根路径等。上面的例子中，在使用API时，https://simple.api/openapi01将作为根节点来访问各种API。
API的操作，用一个YAML的空对象{}先占个位置，可以填充。例如填充下面的内容。

swagger: '2.0'

info:
  version: 1.0.0
  title: Simple API
  description: A simple API to learn how to write OpenAPI Specification

schemes: 
  - https
host: simple.api
basePath: /openapi01

paths:
  /persons:
    get:
      summary: Gets some persons
      description: Returns a list containing all persons.
      responses:
        200:
          description: A list of Person
          schema:
            type: array
            items:
              required:
                - username
              properties:
                firstName:
                  type: string
                lastName:
                  type: string
                username:
                  type: string

然后在Swagger Editor就可以看到效果。
在这里插入图片描述
我们添加了一个/persons的路径，用来访问一组用户信息。然后在路径中，我们可以添加任意的HTTP动词来操作所需要的资源。例如上面在/persons路径中添加get方法，同时还添加了一些简单的描述信息。
接着用responses定义响应类型，可以在responses中添加任意的HTTP状态码，比如200，404等。这个例子中我们添加的200的响应。
接着定义Get /persons这个接口的响应内容，通过schema属性来描述具体的返回内容。上面例子中，一个用户信息就是一个数组，每个数组元素则是一个用户信息对象，该对象包含三个string类型的属性（properties）：firstName、lastName、username，其中username是必须提供的（required）
有了响应内容，当然应该也会有请求参数。例如：

swagger: '2.0'

info:
  version: 1.0.0
  title: Simple API
  description: A simple API to learn how to write OpenAPI Specification

schemes: 
  - https
host: simple.api
basePath: /openapi01

paths:
  /persons:
    get:
      summary: Gets some persons
      description: Returns a list containing all persons. The list supports paging.
#START############################################################################
      parameters:
       - name: pageSize
         in: query
         description: Number of persons returned
         type: integer
       - name: pageNumber
         in: query
         description: Page number
         type: integer
# END ############################################################################
      responses:
        200:
          description: A list of Person
          schema:
            type: array
            items:
              required:
                - username
              properties:
                firstName:
                  type: string
                lastName:
                  type: string
                username:
                  type: string

增加参数，我们需要使用parameters属性。例如上面例子中，我们加了两个参数，名字name分别叫pageSize和pageNumber。用来进行查询分页，他们的类型type都是整型。可以使用description对参数进行简单描述。
这样，用户就可以通过get /persons?pageSize=10&pageNumber=3来访问第三页的用户信息，查询不超过10条。
in属性指定参数位置，例如上面两个参数属于query查询，也可以是path，路径中。
在这里插入图片描述
当我们查询的参数是body参数时，可以像下面定义。

#START############################################################################
    post:
      summary: Creates a person
      description: Adds a new person to the persons list.
      parameters:
        - name: person
          in: body
          description: The person to create.
          schema:
            required:
              - username
            properties:
              firstName:
                type: string
              lastName:
                type: string
              username:
                type: string
      responses:
        204:
          description: Persons succesfully created.
        400:
          description: Persons couldn't have been created.
# END ############################################################################

如图，首先需要添加post操作，接下来定义消息体参数。通过in属性显示说明参数是在body中。
在这里插入图片描述
上面的定义中，接口的响应参数都相同。这种情况下，我们可以使用definitions来简化代码。definitions可以用来定义常用的内容，定义完成后，我们就可以使用reference属性来引用，也就是$ref。

swagger: "2.0"

info:
  version: 1.0.0
  title: Simple API
  description: A simple API to learn how to write OpenAPI Specification

schemes:
  - https
host: simple.api
basePath: /openapi101

paths:
  /persons:
    get:
      summary: Gets some persons
      description: Returns a list containing all persons. The list supports paging.
      parameters:
       - name: pageSize
         in: query
         description: Number of persons returned
         type: integer
       - name: pageNumber
         in: query
         description: Page number
         type: integer
      responses:
        200:
          description: A list of Person
          schema:
#START############################################################################
            $ref: "#/definitions/Persons"
# END ############################################################################
    post:
      summary: Creates a person
      description: Adds a new person to the persons list.
      parameters:
        - name: person
          in: body
          description: The person to create.
          schema:
#START############################################################################
            $ref: "#/definitions/Person"
# END ############################################################################
      responses:
        204:
          description: Persons succesfully created.
        400:
          description: Persons couldn't have been created.
  /persons/{username}:
    get:
      summary: Gets a person
      description: Returns a single person for its username.
      parameters:
        - name: username
          in: path
          required: true
          description: The person's username
          type: string
      responses:
        200:
          description: A Person
          schema:
#START############################################################################
            $ref: "#/definitions/Person"
# END ############################################################################
        404:
          description: The Person does not exists.

#START 新增定义####################################################################
definitions:
  Person:
    required:
      - username
    properties:
      firstName:
        type: string
      lastName:
        type: string
      username:
        type: string
  Persons:
    type: array
    items:
      $ref: "#/definitions/Person"
# END 新增定义####################################################################

如果你要引用本地文件person.yaml了里面的Person定义。例如；

Person:
  required:
    - username
  properties:
    firstName:
      type: string
    lastName:
      type: string
    username:
      type: string

然后在当前文档中这样引用：$ref: "person.yaml#/Person"。

参考文章

Swagger从入门到精通