我一直在关注asp.net Web Api，我喜欢实现实用网络服务的简单性。
但是，我如何记录/指定这样实现的服务的接口？例如，我是否可以传递或生成没有.NET背景的Java人员，以便让他轻松调用和使用服务？我能给javascript的家伙什么？
理想情况下，我喜欢SOAP / XSD的好处或类似的东西（很容易用很好的类型对象反序列化），同时保留一个可以从Web浏览器调用的服务（即支持非crufy） JSON）。
值得注意的是，自从我最初发布这个问题以来，我发现ServiceStack更自然地处理了这个问题;支持JSON，SOAP和WSDL开箱即用，为客户选择相同的服务。如果你真的想要SOAP + JSON，那么它可能是一个比ASP.NET Web Api更好的框架。
答案 0 :(得分：11)
2016年3月更新
已经有一段时间了，因为这个问题得到解答，并且用于记录任何Rest API的工具已经出现了很多。我们目前正在评估Swagger 2.0现在正在产生Open Api Initiative，RAML和API Blueprint。
对于WebAPI项目，有一个工具Swashbuckle可自动创建Swagger（Open API）格式文档。
记录REST服务的格式：
有一些尝试构建和标准化REST服务的描述：
我认为可以说上述两种方法都没有被广泛采用，但是WADL看起来确实是一种非常简洁的格式 - 顶部的快速XSLT，它可能是一种很好的人类可读格式。在apigee github网站here上有很多着名API的WADL示例。
当试图找到合适的文档格式时，我倾向于从其他人那里寻找“灵感”...... Apigee在这方面进行了大量的研究，并将其作为其API之一的文档{{3}或者看一下Facebook的社交图谱api here。
示例基本上与建议here
一致如何自动记录：
使用.NET：有一个自动生成WebApi“帮助”页面here的好例子。这个例子的逻辑扩展可能是让它在WADL格式化版本中出来......
使用Java：here是Java社区中用于自动生成WADL的工具。
与其他开发者分享的内容：
你的Javascript家伙很可能想要一本像Facebook和apigee这样的手册;提供资源，网址，响应代码等的开发示例。这里最重要的是支持JSON作为主要内容类型，这对他/她来说最容易消费和使用。
您的Java人员也需要手册，但理论上也可以为您发送/使用的资源的任何XML表示提供示例XSD（假设他们将请求作为“Content-Type：appplication / xml”） 。这个可能帮助他们构建代理类等.JSON到Java和.NET转换器可以在线获得，并且在手册中给出了示例资源，他们应该能够使用这些类型的服务之一来快速创建代理。 Jersey。
如果你绝对必须有自动发现，自动代理生成等，那么你可能需要选择两个 REST和SOAP（带有WSDL）端点 - 相关问题：Generate Java class from JSON?
答案 1 :(得分：5)
您可以使用IApiExplorer界面和ApiExplorer课程来为您的Web Api服务创建帮助页面。此帮助页面将描述您的服务公开的REST方法，因此任何了解REST如何工作的开发人员都可以使用它（无论语言如何）。请阅读以下链接了解详情和样本：