对于 REST API 的开发者而言,不管是对内作为团队的开发文档,还是对外作为给用户的说明文档,API 文档都是不可或缺的。
然而 “文档是死的、代码是活的”,在现实中,文档跟不上代码的更新节奏的情况比比皆是。如何编写 实时更新的 、易于阅读的 文档成了一个普遍的难题。由此,API 描述语言应用而生。
Swagger 是一个简单但功能强大的 API 表达工具。它具有地球上最大的 API 工具生态系统。数以千计的开发人员,使用几乎所有的现代编程语言,都在支持和使用 Swagger。使用 Swagger 生成 API,我们可以得到交互式文档,自动生成代码的 SDK 以及 API 的发现特性等(参考 使用Swagger生成RESTful API文档 )。
Swagger 的功能很丰富,但在这里我们只关心一点:如何基于简单的 Swagger 描述语言,为 REST API 生成易读的 Markdown 离线文档。
一、基于 Swagger Spec 编写 API 描述文档 这一步无需多说,打开你喜欢的编辑器,或者使用官方的 Swagger Editor ,参考 Spec 语法 编写即可。
这里我们以 petstore-minimal.yaml 为例:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 --- swagger: "2.0" info: version: "1.0.0" title: "Swagger Petstore" description: "A sample API that uses a petstore as an example to demonstrate features in the swagger-2.0 specification" termsOfService: "http://swagger.io/terms/" contact: name: "Swagger API Team" license: name: "MIT" host: "petstore.swagger.io" basePath: "/api" schemes: - "http" consumes: - "application/json" produces: - "application/json" paths: /pets: get: description: "Returns all pets from the system that the user has access to" produces: - "application/json" responses: "200": description: "A list of pets." schema: type: "array" items: $ref: "#/definitions/Pet" definitions: Pet: type: "object" required: - "id" - "name" properties: id: type: "integer" format: "int64" name: type: "string" tag: type: "string"
二、安装转换工具 Swagger2Markup Swagger2Markup 是一个 Java 编写的工具,用于将 Swagger 文档转换为 AsciiDoc 或者 Markdown 文档。简直就是为我们这里的需求量身定做的 :-)
安装 Swagger2Markup 的步骤如下:
1. 安装 Java 以 Ubuntu 为例,参考 How To Install Java on Ubuntu with Apt-Get 和 Ubuntu 安装 JDK 7 / JDK8 的两种方式 :
安装默认的 JRE/JDK
1 2 3 4 5 $ sudo apt-get update $ $ sudo apt-get install default-jre $ $ sudo apt-get install default-jdk
安装 Oracle JDK 8
1 2 3 4 5 $ $ sudo add-apt-repository ppa:webupd8team/java $ sudo apt-get update $ $ sudo apt-get install oracle-java8-installer
2. 下载 Swagger2Markup 的命令行工具 参考 Command Line Interface ,下载最新的 jar 包(当前为 swagger2markup-cli-1.3.1.jar )即可。
三、使用 Swagger2Markup 将 Swagger 转换为 Markdown 参考 Command Line Interface 中的步骤:
1. 创建一个 config.properties
配置文件 设置 markupLanguage 为 MARKDOWN
1 swagger2markup.markupLanguage =MARKDOWN
2. 将 Swagger 转换为 Markdown 1 $ java -jar swagger2markup-cli-1.3.1.jar convert -i /path/to/petstore-minimal.yaml -f /tmp/petstore-minimal -c /path/to/config.properties
3. 查看生成的文档 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 # Swagger Petstore <a name="overview" ></a> ## Overview A sample API that uses a petstore as an example to demonstrate features in the swagger-2.0 specification ### Version information *Version* : 1.0 .0 ### Contact information *Contact* : Swagger API Team ### License information *License* : MIT *Terms of service* : http: ### URI scheme *Host* : petstore.swagger.io *BasePath* : /api *Schemes* : HTTP ### Consumes * `application/json` ### Produces * `application/json` <a name="paths" ></a> ## Paths <a name="pets-get" ></a> ### GET /pets #### Description Returns all pets from the system that the user has access to #### Responses |HTTP Code|Description|Schema| |---|---|---| |**200 **|A list of pets.|< [Pet](#pet) > array| #### Produces * `application/json` <a name="definitions" ></a> ## Definitions <a name="pet" ></a> ### Pet |Name|Schema| |---|---| |**id** <br>*required*|integer (int64)| |**name** <br>*required*|string| |**tag** <br>*optional*|string|
四、CLI as a service 如果团队内部人员都会用到这个工具,但是又不想在每个人的电脑上都安装 Java 和 Swagger2Markup,这时可以基于命令行工具 Swagger2Markup 提供一个 “文档转换服务”。
作为示例,以下是使用 Python 语言并且借助 RESTArt 库实现的一个 “文档转换服务”:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 import osimport tempfilefrom restart import statusfrom restart.api import RESTArtfrom restart.parsers import Parserfrom restart.renderers import Rendererfrom restart.resource import Resourceapi = RESTArt() class SwaggerParser (Parser ): content_type = 'text/plain' def parse (self, stream, content_type, content_length, context=None ): return stream.read().decode('utf-8' ) class MarkdownRenderer (Renderer ): content_type = 'text/plain' format_suffix = 'md' def render (self, data, context=None ): return data.encode('utf-8' ) @api.register class SwaggerMarkdownDocs (Resource ): name = 'swagger_markdown_docs' parser_classes = (SwaggerParser,) renderer_classes = (MarkdownRenderer,) def create (self, request ): with tempfile.NamedTemporaryFile(suffix='.yml' , delete=False ) as yml: yml_filename = yml.name yml.write(request.data.encode('utf-8' )) with tempfile.NamedTemporaryFile(suffix='.md' , delete=False ) as md: md_filename = md.name jar = '/path/to/swagger2markup-cli-1.3.1.jar' conf = '/path/to/config.properties' os.system('java -jar {jar} convert -i {yml} -f {md} -c {conf}' .format ( jar=jar, yml=yml_filename, md=md_filename[:-len ('.md' )], conf=conf, )) with open (md_filename) as md: content = md.read().decode('utf-8' ) os.unlink(yml_filename) os.unlink(md_filename) return content, status.HTTP_201_CREATED
启动 “文档转换服务”:
1 2 $ restart swagger2markdown:api * Running on http://127.0.0.1:5000/ (Press CTRL+C to quit)
使用 “文档转换服务” 生成 Markdown 文档:
1 $ curl -H 'Content-Type: text/plain' -XPOST http://localhost:5000/swagger_markdown_docs --data-binary @/path/to/petstore-minimal.yaml > /tmp/petstore-minimal.md