swagger是广受欢迎的Restful API设计工具之一，能够方便有效地进行API的设计、共享、管理和测试。
很多时候的使用场景是在服务中集成swagger-ui通过注解来编辑API，通过程序自动生成对应的API，这种方式对代码有一定的侵入性，在共享上也稍显不足，而且这在于你已经想清楚了API应该是如何实现的。实际上在设计阶段，swagger还提供了Swagger Editor工具用于方便地进行API文档的编写和导出分享。
一、安装Swagger Editor
1、配置node环境
Swagger使用node编写，所以在安装使用之前需要先进行node环境的配置，安装好node和npm，node和npm的安装教程网上自行百度。特别提一下，如果下载的速度比较慢，可以更换npm镜像：
npm install -g cnpm --registry=https://registry.npm.taobao.org
2、安装http-server
npm install -g http-server
3、下载swagger-editor并解压缩
4、进入swagger-editor的根目录，执行http-server
5、访问localhost:8080就可以看到swagger-editor的页面了
二、Swagger-Editor的使用
Swagger-Editor 支持yaml格式和Open API 3两种格式，通过“Edit”Tab菜单可以随时进行转换。
同时，支持从URL、从文件中导入，也支持导出称yaml文件或者json格式的文件，还可以十分方便地生成各种形式的server端代码和client端代码，可谓利器。
swagger的语法请参照官方文档，以下是一个简单的案例描述：
swagger: '2.0' info: description: >- This is a sample server Petstore server. You can find out more about Swagger at [http://swagger.io](http://swagger.io) or on [irc.freenode.net, #swagger](http://swagger.io/irc/). For this sample, you can use the api key `special-key` to test the authorization filters. version: 1.0.0 title: Swagger Petstore termsOfService: 'http://swagger.io/terms/' contact: email: apiteam@swagger.io license: name: Apache 2.0 url: 'http://www.apache.org/licenses/LICENSE-2.0.html' host: petstore.swagger.io basePath: /v2 tags: - name: pet description: Everything about your Pets externalDocs: description: Find out more url: 'http://swagger.io' schemes: - https - http paths: /pet: post: tags: - pet summary: Add a new pet to the store description: '' operationId: addPet consumes: - application/json - application/xml produces: - application/xml - application/json parameters: - in: body name: body description: Pet object that needs to be added to the store required: true schema: $ref: '#/definitions/Pet' responses: '405': description: Invalid input definitions: Category: type: object properties: id: type: integer format: int64 name: type: string Tag: type: object properties: id: type: integer format: int64 name: type: string xml: name: Tag Pet: type: object required: - name - photoUrls properties: id: type: integer format: int64 category: $ref: '#/definitions/Category' name: type: string example: doggie photoUrls: type: array xml: name: photoUrl wrapped: true items: type: string tags: type: array xml: name: tag wrapped: true items: $ref: '#/definitions/Tag' status: type: string description: pet status in the store enum: - available - pending - sold xml: name: Pet ApiResponse: type: object properties: code: type: integer format: int32 type: type: string message: type: string externalDocs: description: Find out more about Swagger url: 'http://swagger.io'
- swagger指定了swagger的版本
- info段主要是对于本API文档相关信息的描述
- host是指定API对应服务的host，host和basePath、url共同组成了API的访问路径，可以在后续API文档中通过“try it out”功能进行调用验证。
- basePath指定基础访问路径
- schemes：制定协议
- paths是最重要部分，指定了API的mapping路径，通过parameters段指定了API入参，responses段指定了响应体。
- definitions则是对parameters和responses中提供参数对象作为引用，使得API文档具有层次性。
通过以上方式就可以十分简单快速的编写一个可共享的动态API文档，在实际的使用中，建议使用yaml格式编写API文档，在服务器中部署swagger-editor，用于进行API文档的共享。
