什么是记录/生成一个RESTful / HTTP RPC API参考的最佳工具？ [英] What is the best tool for documenting/generate reference for a RESTful/HTTP RPC API?
问题描述
许多问题已经张贴，并回答了有关REST / HTTP API的基础等，但没有一个似乎对以下问题多的信息：
Many questions have been posted and answered about REST / HTTP based APIs, etc, but none seem to have much information on the following question:
有哪些工具/用于记录一个HTTP-RPC API？
哪些工具是最好的？
What tools are available/used to document a HTTP-RPC API? Which tools are the best?
从2009年1月类似的问题（具体以ASP.NET）可以发现<一个href=\"http://stackoverflow.com/questions/436506/whats-the-best-tool-to-manage-documentation-for-restful-api\">here,但没有答案。
A Similar question (specific to ASP.NET) from Jan 2009 can be found here, but with no answers.
我在开发几个API既专业和个人项目（.NET MVC / OpenRasta，PHP，ColdFusion的，等等）的过程中，我没有发现什么特别帮助文档这些API。我不是基于code-解析/擦洗或类似的东西找自动生成。正如你可能已经知道一个RESTful /基于HTTP的 API 的应该是客户端与平台无关;因此我希望任何文档工具是相同的。
I am in the process of developing several APIs both professionally and for personal projects (.NET MVC/OpenRasta, PHP, Coldfusion, etc..), and I haven't found anything in particular to help document these APIs. I am not looking for auto-generation based on code-parsing/scrubbing or anything like that. As you probably already know a RESTful/HTTP-based API should be client and platform agnostic; as such I would expect any documentation tool to be the same.
功能，一个体面的工具可能有：
Features that a decent tool might have:
- 指定的URL / URI的格式/结构
- 请求/响应格式和方法（GET / POST /等，XML / JSON的/ etc）
- 端点进行分类/ API调用（如身份验证下，分组几个电话）
- 自动生成静态文件的参考/像下面的示例文件
- 的示例包括，测试案例等
下面是什么，我认为体面的API文档/参考（S）看起来像一些例子：
Here are some examples of what I consider decent API documentation/reference(s) look like:
<一个href=\"http://dev.twitter.com/doc/post/statuses/destroy/%3aid\">http://dev.twitter.com/doc/post/statuses/destroy/:id
<一个href=\"http://www.salesforce.com/us/developer/docs/api_rest/index.htm\">http://www.salesforce.com/us/developer/docs/api_rest/index.htm
http://www.flickr.com/services/api/
推荐答案
SWAGGER 可能是值得看看你需要。我用它来记录通过泽西Java应用程序暴露REST的入口点，但它看起来像你可以与其他语言也使用它。
SWAGGER is probably worth a look for you need. I use it for documenting REST entrypoints exposed by a java application using Jersey, but it looks like you can use it with other languages too.
这篇关于什么是记录/生成一个RESTful / HTTP RPC API参考的最佳工具？的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！
