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: fett@intergalactic.com

# 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 都是可以考虑的方案。从来没有放诸四海皆准的所谓最好的工作，都是在工作中不断比较最后才能知道哪个选型最合适。

这个文章的背景过去已经比较久，内容可能已经和现在的方案相去甚远，就此结帖，不再讨论。内容仅供参考！

@Rei @huacnlee @jasl 43楼这位哥算不算打广告，上个月才注册的号，在社区回帖都是清一色的回答？

如果是简单的需求，比如对外部服务请求方式单一，我觉得 net/http 够了，否则，我觉得哪个轻量用哪个，或者是哪个的设计简单用哪个，这会决定后面你排查问题的难易程度。一般来说，库本身性能是我最后考虑的因素，毕竟对于一个外部请求来说，如果不是很高频，代码本身的性能根本不是什么明显的影响因素。

如果是自己开发 gem 包，我会直接使用标准库的包 net/http，目的是减小包的依赖，尽可能轻量。如果是开发的项目，如果是依赖链里边已经有可用的 http 包，我就会直接使用那个包。所以，faraday、httparty、rest-client 这些我都用过，因为维护过的项目都用过。

有试过低版本的 gem 包吗？

我不是说每一本书盗版，事实上我也无法一一查实哪些书涉嫌盗版或者本身是开放版权的。我简单搜索了几本我正在 Kindle 上阅读的电子书，这些书都是我付费下载阅读的，而通过你的资源可以免费从网盘下载。提这个问题只是想提醒你，需要关注盗版内容的甄别。

本站有声明，只做索引和搜索，不缓存，保存任何资源，所有现在链接指向源站。

这个问题我也很好奇，于是从网上搜了答案，讨论的不多，有一点建议你考虑：

这种行为为侵权作品的传播提供了渠道和便利，从而使其链接网站的侵权行为得以实施、扩大和延伸，因此，严格来说，这种行为客观上参与、帮助了其他链接网站实施侵权行为。

原来的问题以及全部答案可以看 https://zhidao.baidu.com/question/941821751360745772.html

另外，就这个问题，我自己也请教了从事知识产权领域的一个律师校友，得到与上述引用内容一致的答案。现在 Ruby-China 的上传图片功能好像有问题，我本来想上传微信聊天截图，但是总是失败，如果你有兴趣了解，可以告诉我一声，我加微信发给你看看。

所以，这是一个盗版书资源的网站？

可以考虑下我给 exception_notification 添加的 Error Grouping 特性，通过 log2(n) 函数，保证同一个错误在第 1, 2, 4, 8, 16, 32, ..., 1024 次报错时才会发出告警，这样哪怕是成千上万次异常产生，通过对数，也可以直接降到很低的告警频率。这样你可以无痛继续使用邮件告警，又可以摆脱大量邮件的困扰。实乃居家旅行上班必备之良药。

我写python的时候，代码打开后首屏就是各式各样的 import，就在我还在庆幸 Ruby 避开了这套 import 设计的时候，然而……