技术写作与文档2015news.ycombinator.com
Ask HN：写 API 规范的最佳方式是什么？
Ask HN: What's the best way to write an API spec?
导读
这是 Hacker News 上一个关于如何写 REST API 规格文档的求助帖，回复里既盘点了当时流行的几种规格格式（JSON Schema、API Blueprint、Swagger、Slate、WADL），也给出了具体的写作方法。对写作者的价值在于：它把“写规格”当成一种克制的说明文写作——先想清楚再动笔、只写该写的、能用表格就别用长篇。
可以直接用的写作要点
- 01
先写清“这个东西做什么、基于哪些假设”，细节只留给容易踩坑的地方；文档写得越全，过时越快，甚至越容易变成彻头彻尾的谎言。
- 02
动笔前先在白板上把每个功能过一遍：它该做什么、不该做什么，很多问题会在这一步冒出来，成品也更好。
- 03
好的规格应该能塞进一张表格；哪怕一个复杂功能， outlining 超过二三十分钟基本就是浪费时间，不如把省下的时间用来画一张清晰的系统级流程图。
- 04
选格式时优先选人可读可写的（比如用 Markdown 写的 API Blueprint），同时看它能否顺带生成校验、mock 服务和客户端代码。
HN 评论精选
规格要简洁、可表格化，先白板推演再动笔，别过度文档化。
写好 API 规格没有什么独门秘诀，但有几点心得：文档越全面，过时、失效乃至“睁眼说瞎话”的速度就越快，所以只定义它做什么、有哪些假设，细节留给“坑”；先上白板，把每个功能该做和不该做都过一遍，光是想清楚这一步就能让最终产品更好；如果你定的格式塞不进表格或电子表格，多半是做错了，别指望 UML 之类框架带来清晰度，哪怕复杂功能，梳理超过二三十分钟就是在浪费时间，不如用这时间去画系统级数据流图；这个阶段不要深挖实现细节，但至少要想到。
deeviant查看英文原文
There is no single secret to making good API specifications. But here are few things I've learned: * The more comprehensive the documentation gets, the the quicker it gets outdated, un-useful, or flat out pants-on-fire lying. Define what the thing does and what assumptions are made, save detail for "gotchas". Be concise. * Start out on a white board, run through each function, what it should do, what it shouldn't. This really is a huge benefit of spec'ing out a api, just sitting there thinking about it, tons of stuff comes up and you come out with a better product in the end. * If the format you came up with can't be put into something like a table or spreadsheet, you probably doing it wrong. Sure you can get some sort of framework that lets you create all sorts of UML and create class/function shells or what have you, but I have never found these to create value or clarity. If you are spending more than 20-30 minutes outlining even a complicated function, your probably wasting time. Use time saved to create a clear system-wide DFD. * Don't go deep into implementation detail at this stage, but at least think about it. Some much time can be saved with a little forethought here.
主流格式各有取舍，没有公认最优，选型要看是否适合超媒体和工具链需求。
这几年 API 规格格式爆发式增长，却没有明显的赢家。JSON Schema 和 JSON Hyperschema 是基于 JSON 描述 JSON 与 REST（超媒体驱动）API 的格式，可用于生成文档、校验器、客户端库和界面。API Blueprint 用 Markdown 写，可读性和可写性都很好，但还不适合超媒体 API，工具链包括校验、客户端生成、mock 服务器和文档生成。Swagger 是基于 YAML 的格式，本意是配合 Swagger UI 生成而不是手写，文档漂亮、能生成客户端，但不适合描述超媒体 API。Slate 更像文档框架/模板，专注生成好看的文档页，不管规格本身。WADL 用 XML 描述 API 交互，类似 WSDL，用的人不多。哪个最好？好问题。
gamache查看英文原文
There have been an explosion of API specification formats in the last few years. No clear winner has emerged. JSON Schema and JSON Hyperschema are JSON-based formats for describing JSON and REST (hypermedia-driven) APIs. The formats make decent sense and can be used to generate docs, validators, client libraries, UIs, and more. http://json-schema.org/ API Blueprint is another emerging format for API description. It's written in Markdown, so it is very human-readable and -writable. It is not yet suitable for hypermedia APIs. Like JSON Schema, its tooling includes validators, client library generators, mock server generators, docs generators, etc. http://apiblueprint.org/ Swagger is a YAML-based format for specifying JSON APIs. It is meant to be created using the Swagger UI, rather than handwritten. It generates pretty docs, client software, etc. but is not suited to describing hypermedia APIs. http://swagger.io Slate is an API documentation framework/template, designed to generate very handsome documentation pages. Its concern is more documentation than specification, and therefore doesn't concern itself with things like library or mock generation. https://github.com/tripit/slate WADL is an API description language which describes API interactions in an XML format. It resembles WSDL. Not many people use it. http://en.wikipedia.org/wiki/Web_Application_Description_Language Which of these is the best? Good question. I like JSON Hyperschema, but I am writing hypermedia APIs and the other formats here are lacking in their hypermedia support. API Blueprint is a nice format to write in a text editor and is easily read as-is or rendered from Markdown; no separate docs generator is necessary.
把规格文件纳入代码仓库、用工具自动生成文档和 mock 后端，能显著简化开发。
我用 apiary.io，这是我找到的最好的写 API 规格的工具。可以在它网站上用在线 API Blueprint 编辑器写规格；也可以把文本文件放进代码仓库，授权 apiary 在你每次提交到 GitHub 时拉取该文件，这样全部工作都在自己的开发环境里完成。它根据规格生成的文档设计得很好、很直观。我最喜欢的功能是它按我的规格提供的 mock 后端服务器：如果做单页应用，写完规格直接把前端指向这个 mock 服务器就行，大大简化了我的开发流程。
DevX101查看英文原文
I used apiary.io which is the best tool I've found for writing API specs. You can write your specs using an online API Blueprint format editor via their site. Alternatively, you can put a text file in your repo and authorize apiary to pull the file every time you make a commit to github. This way you do everything via your development environment. The documentation they provide based on the specs looks very well designed and intuitive. One of my favorite features about apiary was the mock backend server they use based on my API specs. So if you're doing a single page app, just write your specs then point your frontend app to the mock server they provide. This greatly simplified development process for me.
与其手写冗长的 JSON 或依赖代码注解，不如用简短的 DSL 来描述接口。
借这个机会推荐一下我自己的小工具：我用 Swagger，具体说是 Swagger UI 来生成可交互的网页文档。但我不靠源码注解让 Swagger 自动生成文档，也不手写它那套冗长的 JSON，而是为此做了一个小 DSL（swagger-dsl），现在文档还不足，但功能完全可用，我经常用。
rodw查看英文原文
I guess I'll take this opportunity to plug my own little tool for this. I use Swagger [1] and more specifically Swagger UI [2] to generate interactive web-based documentation like the sample at [3]. But rather than relying upon source code annotations to have swagger auto-generate the documentation, or hand-writing swagger's verbose JSON structure, I created a little DSL for it as demonstrated at [4] and available on GitHub at [5]. Let me know if you have any questions about swagger-dsl. It's under-documented right now but perfectly functional. I use it often. [1] http://swagger.io/ [2] https://github.com/swagger-api/swagger-ui [3] http://petstore.swagger.wordnik.com/#!/pet [4] http://intellinote.github.io/swagger-dsl/demo/live.html [5] https://github.com/intellinote/swagger-dsl
同类还值得读
编写更好文档的框架
A Framework for Writing Better Documentation
这是 Divio 的文档写作框架，把技术文档按「读者的目标」分成四类：教程（学习导向）、操作指南（问题导向）、参考（信息导向）、解释（理解导向）。
技术写作与文档2021 · 637 分 · 76 评4 条写作要点编辑精选写好一份设计文档
Writing a good design document
这篇 HN 帖子标题为《Writing a good design document》，主题是如何写好一份设计文档；对写作者来说，它值得作为技术写作和结构化说明文的参照。
技术写作与文档2025 · 581 分 · 147 评3 条写作要点编辑精选技术写作课程
Technical Writing Courses
这是 Google 官方免费技术写作课程（两门），讲受众定义、主动语态、短句、文档结构等基础方法。
技术写作与文档2020 · 571 分 · 73 评4 条写作要点编辑精选写出更好的错误信息
Write better error messages
这篇帖子讨论如何写出更好的错误信息，评论补充了开发者场景下的具体做法和真实反面案例。
技术写作与文档2022 · 566 分 · 253 评4 条写作要点编辑精选写一本技术书的经济账
The Economics of Writing a Technical Book
一位技术书作者拆解写书的真实经济账：版税收入往往远低于投入的时间成本。
技术写作与文档2018 · 519 分 · 149 评4 条写作要点编辑精选