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"。
参考文章
扫一扫
被折叠的 条评论
为什么被折叠?
到【灌水乐园】发言
