我一直在关注asp.net Web Api，我喜欢实现实用 Web 服务的简单性。
但是，我如何记录/指定这样实现的服务的接口？例如，是否有任何规范可以传递或生成给没有 .NET 背景的 Java 人员，让他轻松调用和使用服务？我可以给 javascript 人什么？
理想情况下，我希望 SOAP/XSD 或类似的东西（易于使用类型良好的对象反序列化）的好处，同时保留可从 Web 浏览器调用的服务（即支持非繁琐JSON）。
值得注意的是，自从我最初发布这个问题后，我发现ServiceStack 更自然地处理了这个问题；根据客户的选择，支持开箱即用的 JSON、SOAP 和 WSDL 以用于相同的服务。如果你真的想要 SOAP+JSON，它可能是比 ASP.NET Web Api 更好的框架。
【问题讨论】：
标签： json soap xsd asp.net-web-api
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 之一的文档here 或看看 Facebook 的社交图 apihere。
例子与here的建议基本一致
如何自动记录：
使用 .NET：有一个自动生成 WebApi“帮助”页面here 的好例子。这个例子的一个逻辑扩展可能是让它也可以使用 WADL 格式的版本......
使用 Java：Jersey 是 Java 社区中用于自动生成 WADL 的工具。
与其他开发者分享的内容：
您的 Javascript 人员很可能想要一本像 Facebook 和 apigee 这样的手册；提供资源、url、响应代码等的开发示例。这里最重要的是支持 JSON 作为主要内容类型，这将是他/她迄今为止最容易使用和使用的内容。
您的 Java 人员也需要该手册，但理论上他们可以为您发送/使用的资源的任何 XML 表示形式提供示例 XSD（假设他们以“Content-Type：appplication/xml”的形式提出请求） .这可能帮助他们构建代理类等。JSON 到 Java 和 .NET 转换器可在线获得，并且鉴于您手册中的示例资源，他们应该能够简单地使用这些类型的服务之一来快速创建代理。 Generate Java class from JSON?。
如果您绝对必须具有自动发现、自动代理生成等功能，那么您可能需要提供 REST 和 SOAP（带有 WSDL）端点的选择 - 相关问题在这里：ReST Proxy Object Generator。
【讨论】：
您可以使用IApiExplorer 接口和ApiExplorer 类来为您的Web Api 服务创建帮助页面。此帮助页面将描述您的服务公开的 REST 方法，因此任何了解 REST 工作原理的开发人员都可以使用它（无论使用哪种语言）。请阅读以下链接以获取详细信息和示例：
【讨论】：