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