记录/生成 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)此处，但没有答案.
A Similar question (specific to ASP.NET) from Jan 2009 can be found here, but with no answers.
我正在为专业和个人项目(.NET MVC/OpenRasta、PHP、Coldfusion 等)开发多个 API，但我没有找到任何特别有助于记录这些 API 的内容.我不是在寻找基于代码解析/清理或类似的东西的自动生成.您可能已经知道基于 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/etc、XML/JSON/etc)
- 对端点/API 调用进行分类(例如在身份验证下对多个调用进行分组)
- 自动生成静态参考文件/文档，如下面的示例
- 包括示例、测试用例等
以下是我认为不错的 API 文档/参考文件的一些示例:
Here are some examples of what I consider decent API documentation/reference(s) look like:
http://dev.twitter.com/doc/post/状态/销毁/:id
http://www.salesforce.com/us/developer/docs/api_rest/index.htm
http://www.flickr.com/services/api/>
推荐答案
SWAGGER 可能值得一看你需要.我使用它来记录使用 Jersey 的 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屋！
