Swagger是基于OpenAPI的，OpenAPI支持YAML和JSON格式描述API。YAML相对于JSON来说更加简洁，比较适合做简洁的序列化和配置文件。编写YAML文档推荐使用Swagger Editor，它提供了语法高亮、自动完成、即时预览等功能。编辑器可以在本地使用，也可以在线使用。YAML的数据结构可以用类似大纲的缩排方式呈现，结构通过缩进来表示，连续的项目通过“-”来表示，map结构里面的key/value对用“:”来分隔。
基于Swagger Editor设计API，可以直接在线编辑API，也可以在本地安装，下面以在线编辑器为例介绍如何基于Swagger构建API。
（1）访问官方Editor编辑器
（2）编辑YAML文件，如下所示。
swagger: "2.0" info: version: 1.0.0 title: Product API description: Product API for test schemes: - https host: localhost basePath: /product paths: {}
下面简单说明一下这个文档。首先，显示OpenAPI使用的版本是2.0。
swagger: "2.0"
API的描述信息，包括如API文档版本（version）、API文档名称（title）和描述信息（description）。
info: version: 1.0.0 title: Product API description: Product API for tes
下面的代码表示API的URL，采用HTTPS协议，介绍了主机名（host）、根路径（basePath）。
schemes: - https host: localhost basePath: /product
下面我们来看一个稍复杂一点的示例。
swagger: '2.0' info: version: '1.0' title: Swagger构建RESTful API host: 'localhost:8080' basePath: / tags: - name: product-controller description: Product Controller paths: /products: get: tags: - product-controller summary: 获取产品列表 description: 获取产品列表 operationId: getProductListUsingGET consumes: - application/json produces: - '*/*' responses: '200': description: OK schema: type: array items: $ref: '#/definitions/Product' '401': description: Unauthorized '403': description: Forbidden '404': description: Not Found /products/{id}: get: tags: - product-controller summary: 获取产品详细信息 description: 根据URL的id来获取产品详细信息 operationId: getProductUsingGET consumes: - application/json produces: - '*/*' parameters: - name: id in: path description: 产品ID required: true type: integer responses: '200': description: OK schema: $ref: '#/definitions/Product' '401': description: Unauthorized '403': description: Forbidden '404': description: Not Found definitions: Product: type: object properties: count: type: integer format: int32 desc: type: string id: type: integer format: int32 name: type: string
上面的示例定义了两个API，一个是获取Product的列表，一个是根据id获取Product的详情。
编辑完成后，可以得到如图2-17所示的文档界面。
（3）点击file-download yaml下载YAML文件。
（4）点击generate server下载服务端，点击generate client下载客户端，可以分别生成相应语言的SDK工程。
