我一直在看 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 现在产卵了 开放Api计划， 肾错构瘤 和 API蓝图。
对于WebAPI项目，有一个工具 Swashbuckle 自动创建Swagger（Open API）格式文档。
用于记录REST服务的格式：
有一些尝试构建和标准化REST服务的描述：
我认为可以说上述两种方法都没有被广泛采用，但是WADL确实看起来像一个简洁的格式 - 一个快速的XSLT顶部，它可能是一个很好的人类可读格式。在apigee github网站上有很多着名API的WADL示例 这里。
当试图找到合适的文档格式时，我倾向于从其他人那里寻找“灵感”...... Apigee在这个领域做了很多研究并将其作为其API之一的文档 这里 或者看看Facebook的社交图api 这里。
这些例子基本上符合建议 这里
如何自动记录：
使用.NET：有一个自动生成WebApi“帮助”页面的好例子 这里。这个例子的逻辑扩展也可能是为了让它在WADL格式化的版本中运行...
使用Java： 新泽西 是Java社区中用于自动生成WADL的工具。
与其他开发者分享的内容：
你的Javascript家伙很可能想要一本像Facebook和apigee这样的手册;提供资源，网址，响应代码等的开发示例。这里最重要的是支持JSON作为主要内容类型，这对他/她来说最容易消费和使用。
您的Java人员也需要手册，但理论上也可以为您发送/使用的资源的任何XML表示提供示例XSD（假设他们将请求作为“Content-Type：appplication / xml”）。这个 可能 帮助他们构建代理类等.JSON到Java和.NET转换器可以在线获得，并且在手册中给出了示例资源，他们应该能够使用这些类型的服务之一来快速创建代理。 从JSON生成Java类？。
如果你绝对必须有自动发现，自动代理生成等，那么你可能需要提供一个选择 都 REST和SOAP（带WSDL）端点 - 相关问题： ReST代理对象生成器。
您可以使用 IApiExplorer 界面和 ApiExplorer class，以便为您的Web Api服务创建帮助页面。此帮助页面将描述您的服务公开的REST方法，因此任何了解REST如何工作的开发人员都可以使用它（无论语言如何）。请阅读以下链接了解详情和样本：
2016年3月更新
已经有一段时间了，因为这个问题得到了解答，并且用于记录任何Rest API的工具已经出现了很多。我们目前正在评估 Swagger 2.0 现在产卵了 开放Api计划， 肾错构瘤 和 API蓝图。
对于WebAPI项目，有一个工具 Swashbuckle 自动创建Swagger（Open API）格式文档。
用于记录REST服务的格式：
有一些尝试构建和标准化REST服务的描述：
我认为可以说上述两种方法都没有被广泛采用，但是WADL确实看起来像一个简洁的格式 - 一个快速的XSLT顶部，它可能是一个很好的人类可读格式。在apigee github网站上有很多着名API的WADL示例 这里。
当试图找到合适的文档格式时，我倾向于从其他人那里寻找“灵感”...... Apigee在这个领域做了很多研究并将其作为其API之一的文档 这里 或者看看Facebook的社交图api 这里。
这些例子基本上符合建议 这里
如何自动记录：
使用.NET：有一个自动生成WebApi“帮助”页面的好例子 这里。这个例子的逻辑扩展也可能是为了让它在WADL格式化的版本中运行...
使用Java： 新泽西 是Java社区中用于自动生成WADL的工具。
与其他开发者分享的内容：
你的Javascript家伙很可能想要一本像Facebook和apigee这样的手册;提供资源，网址，响应代码等的开发示例。这里最重要的是支持JSON作为主要内容类型，这对他/她来说最容易消费和使用。
您的Java人员也需要手册，但理论上也可以为您发送/使用的资源的任何XML表示提供示例XSD（假设他们将请求作为“Content-Type：appplication / xml”）。这个 可能 帮助他们构建代理类等.JSON到Java和.NET转换器可以在线获得，并且在手册中给出了示例资源，他们应该能够使用这些类型的服务之一来快速创建代理。 从JSON生成Java类？。
如果你绝对必须有自动发现，自动代理生成等，那么你可能需要提供一个选择 都 REST和SOAP（带WSDL）端点 - 相关问题： ReST代理对象生成器。
您可以使用 IApiExplorer 界面和 ApiExplorer class，以便为您的Web Api服务创建帮助页面。此帮助页面将描述您的服务公开的REST方法，因此任何了解REST如何工作的开发人员都可以使用它（无论语言如何）。请阅读以下链接了解详情和样本：