新手问题 现在 Rails 大家一般用是来生成接口 spec (比如 swagger-ui)?
如题，
找了一圈，没发现有什么好工具（+低代码量）生成 swagger-ui 页面。
感觉这方面社区不受重视还是什么其他原因？
大家的 API 文档是用 swagger 吗？还是有更好的 API spec？
文档最终还是要人工去维护 工具只有辅助
现在比较好的 spec 选择：
简单的直接 rails 原生的 restful 和前端约定好格式，这个就是怎样让双方都方便就怎么来
json-api 也是不错选择，rails 这边的工具链比较完善
如果觉得 json-api 太复杂（确实有点复杂）可以考虑手动裁剪一下，然后自己做（参考第一条）
GraphQL，这个比较新，但也基本可用了
文档工具选择不多 跨语言的 swagger 一个 ruby 专有的 apipie 或者类似的 gem（功能弱，但简单）graphql 本身文档是原生支持
另一个选择是 如果你们团队 mac 为主 试试 paw
Rei
回复
比如：Spring boot 框架可以很好的集成 swagger-ui.html，
只要在接口的上面加些注解，就可以自动生成对应的“API 文档网页” - 可以填参数，直接发请求
http://blog.didispace.com/springbootswagger2/ Spring Boot 中使用 Swagger2 构建强大的 RESTful API 文档
Rails 中不知道用什么库？
可以试一下 rswag 通过写spec测试来生成swagger.json 使用swagger-ui来渲染swagger页面
如果你使用jsonapi 可以试一下这个jsonapi-swagger将jsonapi resource对象直接生成swagger.json,
可以使用这个生成 JSON 形式的 OpenApi documentation，然后用 Swagger-UI 来渲染 JSON documentation。
API 文档这个东西，就我自己而言，用过几个不同的工具，各有特点，简单捋捋：
Swagger
其实 Swagger 本身只是一种 API Specification 语法，基于 JSON 格式，如果是完全按照语法约束手写一份 Swagger API 文档，估计会把人整疯。很多时候谈到 Swagger，其实大家更多是说的 Swagger API specification generator + Swagger UI，比如 Grape 就有开箱即用的 grape-swagger。这类方案于我而言，最大的问题是需要在代码中写文档，对于文档先行的团队开发协作来说，这种方式有点本末倒置，另外就是会将文档和代码混在一起，一个 controller 文件的行数，轻轻松松成百上千行。除此之外，使用者还需要熟悉这类 Swagger API specification generator 定义的 DSL 或者特殊的标记语法，更别说可能某些包的实现还有各种配置要求，都是学习的成本，还没有通用性，换个包或者换个语言就又不一样了。
官方的随便找的一个实例：
desc 'Attach a field to an entity through a PUT',
success: [
{ code: 201, model: Entities::UseResponse, message: 'Successfully created' },
{ code: 204, message: 'Already exists' }
],
failure: [
{ code: 400, message: 'Bad request' },
{ code: 404, message: 'Not found' }
]
put do
# your code comes here
end
apipie-rails
apipie-rails 是我继 swagger 之后使用过的另一个文档工具，如名字所言，也是在 Rails 项目中集成。特点是比 swagger 轻量，DSL 设计主要针对 Restful API 而生，但是仍然需要熟悉一套它的 DSL，概念还挺多，有个比较完整的官方示例：
resource_description do
short 'Site members'
formats ['json']
param :id, Fixnum, :desc => "User ID", :required => false
param :resource_param, Hash, :desc => 'Param description for all methods' do
param :ausername, String, :desc => "Username for login", :required => true
param :apassword, String, :desc => "Password for login", :required => true
end
api_version "development"
error 404, "Missing"
error 500, "Server crashed for some <%= reason %>", :meta => {:anything => "you can think of"}
error :unprocessable_entity, "Could not save the entity."
returns :code => 403 do
property :reason, String, :desc => "Why this was forbidden"
end
meta :author => {:name => 'John', :surname => 'Doe'}
deprecated false
description <<-EOS
== Long description
Example resource for rest api documentation
These can now be accessed in <tt>shared/header</tt> with:
Headline: <%= headline %>
First name: <%= person.first_name %>
If you need to find out whether a certain local variable has been
assigned a value in a particular render call, you need to use the
following pattern:
<% if local_assigns.has_key? :headline %>
Headline: <%= headline %>
<% end %>
Testing using <tt>defined? headline</tt> will not work. This is an
implementation restriction.
=== Template caching
By default, Rails will compile each template to a method in order
to render it. When you alter a template, Rails will check the
file's modification time and recompile it in development mode.
EOS
end
apipie-rails 从我个人角度，主要的特点是比 swagger-grape-rails 轻量，其他一些我所不喜欢的点，两者都是臭味一致。
slate
事实上，上面两个工具并不是我特别想要介绍的，因为用过之后，总觉得心里别扭。去年偶然间发现了一个基于 Markdown 的 API 文档工具，Slate，这玩意非常轻量，而且是 Markdown，并且基本没有太多复杂的语法约束，我个人非常喜欢。基于 Markdown 语法的 API 文档其实也很多选择，比如 API Blueprint，但是后者比较麻烦的是仍然定义了过多的语法约束，比如官网首页的实例：
# Data Structures
## Blog Post (object)
+ id: 42 (number, required)
+ text: Hello World (string)
+ author (Author) - Author of the blog post.
## Author (object)
+ name: Boba Fett
+ email: [email protected]
# Blog Posts [/posts]
## Retrieve All Posts [GET]
+ Response 200 (application/json)
+ Attributes (array[Blog Post])
从 Slate 的语法上看，Slate 基本没有语法约束，基本上是完整的自由，生成的 HTML 页面也非常简洁漂亮。
现在我所在的公司并没有 Ruby 的技术栈，所以我用的是 Slate 的 Python 版本 plate，结合 GitLab CI 以及公司的 Ceph，实现每次改完文档 git push 之后，就自动在 GitLab CI runner 里构建好静态网页，上传到公司 Ceph（兼容 AWS S3 API 的一套分布式文件系统），就完成自动更新文档了。
使用 Slate 或者 Plate，满足了我们团队文档先行的协作流程，同时文档和代码分离，语法也非常轻便，就是普通的 Markdown 语法。
小结
不同的工具各有利弊，虽然我个人优先考察 Slate，但是我仍然建议根据项目实际情况来选型，比如我们有另外一个团队，前端希望通过 API specification 来自动生成代码，在这种前提下，我就更支持类似 Swagger 这类有强约束的 API 文档规范。
文档只是为了沟通，找到一种方便 API 使用方以及实现方之间沟通，同时维护成本也低的方案，才是目的。更甚者，如果一份 API 文档的设计，需要双方标注讨论，那我觉得类似 Confluence 或者 Google docs 都是可以考虑的方案。从来没有放诸四海皆准的所谓最好的工作，都是在工作中不断比较最后才能知道哪个选型最合适。