相关疑难解决方法(0)

我正在为新的内部Web服务编写RESTful API规范.这不是很长很简单,但即便如此,这是我第一次使用严格的REST(而不是出于实际原因作弊 - 避免PUT,DELETE因为它们是PHP的痛苦,等等).我想知道是否有任何标准方法或最佳实践来记录REST接口？我希望团队的其他成员能够一目了然地理解它,对于任何想要编写客户端的人来说,如果不了解底层代码就能够这样做.

我使用Java Jersey(和JAXB)编写了一个非常广泛的REST API.我还使用Wiki编写了文档,但它是一个完全手动的过程,非常容易出错,特别是当我们需要进行修改时,人们往往忘记更新wiki.

从四处查看,大多数其他REST API也可以手动创建文档.但我想知道这是否可能是一个很好的解决方案.

需要为每个端点记录的事物类型是:

• 服务名称
• 类别
• URI
• 参数
• 参数类型
• 响应类型
• 响应类型架构(XSD)
• 样本请求和响应
• 请求类型(获取/放置/发布/删除)
• 描述
• 可能返回的错误代码

然后当然有一些全球性的事情,如

• 安全
• REST概述
• 错误处理
• 等等

这些一般的东西可以描述一次并且不需要自动化,但对于Web服务方法本身来说,似乎非常希望自动化它.

我想过可能会使用注释,编写一个生成XML的小程序,然后是一个XSLT,它应该用HTML生成实际的文档.使用自定义XDoclet更有意义吗？

我正在通过Http设计类似REST的API.

我需要API客户端(应用程序,而不是浏览器)来关注链接(HATEOAS),而不是构建它们.
此外,由于某些可能不同意的原因,我仍然会使用可读的URL .但是,如果存在相当的方式文档的URL模板(像 这些 的人),我不认为这是正确的做法,因为它可以清楚地吸引和合法的开发人员可以构建自己的网址.

那么,如何以尊重HATEOAS的方式记录API？

我们经常发现与HATEOAS相关的可发现性.
说实话,我不认为这在现实生活中是不够的:商业概念是多重的,微妙的理解和客户开发人员不是你的队友.
有意义的名字显然是不够的.

开发人员需要制作客户端应用..

1. 从条目URL 导航到相关文档的API
2. 构建有效的请求(参数和实体)并解释响应,而不会在语义上产生歧义.

那么,如何记录这个？

• 是否存在以这种方式生成文档的现有工具？
• "词汇表"是否足以填补可发现性和明确解释之间的差距？
• 也许API的HTML表示(Accept:text/html)可以返回人类可读的文档......
• ..对此有任何其他想法或经验吗？

相关概念:
使用Intent,Versioning,Level 3 API进行设计