ASP.NET web api:记录/指定服务 [英] ASP.NET web api: documenting/specifying a service
问题描述
我一直在研究 asp.net Web Api，我喜欢它的简单性实施实用的网络服务.
I've been looking at asp.net Web Api, and I like the simplicity of implementing a practical web service.
但是，我如何记录/指定这样实现的服务的接口?例如，是否有任何规范我可以传递或生成给没有 .NET 背景的 Java 人，让他轻松调用和使用服务?我可以给 javascript 专家什么?
However, how can I document/specify the interface of a service implemented like that? For example, is there any spec I can pass on or generate to a Java guy with no .NET background that will let him easily call and consume the service? What can I give to the javascript guy?
理想情况下，我希望 SOAP/XSD 或类似的东西(易于使用类型良好的对象反序列化)为 Java 人员带来好处，同时保留可从 Web 浏览器调用的服务(即支持 non-crufyJSON).
Ideally, I'd like the benefits of SOAP/XSD or something like it (easy to deserialize with nicely typed objects) for the java guy, while retaining a service that's callable from a web browser too (i.e. supports non-crufy JSON).
值得注意的是，自从我最初发布这个问题以来，我发现 ServiceStack 可以更自然地处理这个问题；根据客户端的选择，支持 JSON、SOAP 和 WSDL 开箱即用的相同服务.如果你真的想要 SOAP+JSON，它可能是一个比 ASP.NET Web Api 更好的框架.
It's worth noting that since I originally posted this question, I discovered ServiceStack which deals with this more naturally; supporting JSON, SOAP, and WSDL out of the box for the same service, as the client chooses. If you really want SOAP+JSON, it may be a better framework than ASP.NET Web Api.
推荐答案
2016 年 3 月更新
自从回答这个问题以来已经有一段时间了，用于记录任何 Rest API 的工具已经出现了很多.我们目前正在评估 Swagger 2.0 现在正在向 开放 API 倡议、RAML 和 API 蓝图.
It has been a while since this was answered and the tooling for documenting any Rest API has come along a lot. We are currently evaluating Swagger 2.0 now spawning out to the the Open Api Initiative, RAML and API Blueprint.
对于 WebAPI 项目，有一个工具 Swashbuckle 可自动创建 Swagger(开放 API)格式文档.
For WebAPI projects there is a tool Swashbuckle that auto creates Swagger (Open API) format documentation.
记录 REST 服务的格式:
在结构化和标准化 REST 服务的描述方面有一些尝试:
There are some attempts at structuring and standardising the description of REST services:
我认为可以公平地说，上述两种方法都没有被广泛采用，但 WADL 确实看起来像一种很好的简洁格式 - 顶部的快速 XSLT，它可能是一种很好的人类可读格式.在 apigee github 站点 这里 上有许多用于一些著名 API 的 WADL 示例.
I think it is fair to say neither of the two approaches above have very wide adoption, but WADL does look like a nice concise format - a quick XSLT over the top and it could be a nice human readable format. There lots of examples of WADL for some famous API's at the apigee github site here.
在尝试寻找合适的文档格式时，我倾向于从其他人那里寻找灵感"..."http://apigee.com/docs/usergrid/content/app-services-resources" rel="nofollow noreferrer">这里 或者看看 Facebook 的社交图 api 此处.
When trying to find a documentation format that is appropriate I tend to look for "inspiration" from others.... Apigee do a lot of research in this area and have this as documentation for one of their API's here or take a look at Facebook's social graph api here.
示例在很大程度上符合建议 这里
The examples are largely in line with the advise here
如何自动记录:
使用.NET:有一个自动生成WebApi帮助"页面的好例子此处.这个例子的一个逻辑扩展可能是让它输出一个 WADL 格式的版本......
Using .NET: There is a good example of auto generating a WebApi "help" page here. A logical extension of this example may be to get it outing a WADL formated version as well...
使用 Java:Jersey 是 Java 社区中用于生成 WADL 的工具自动.
Using Java: Jersey is a tool used in the Java community to generate WADL automatically.
与其他开发者分享的内容:
您的 Javascript 专家很可能想要一本像 Facebook 和 apigee 这样的手册；提供资源、网址、响应代码等的开发示例.这里最重要的是支持 JSON 作为主要内容类型，这将是他/她迄今为止最容易使用和使用的内容.
Your Javascript guy will most likely want a manual like the Facebook and apigee one; giving the dev examples of the resources, urls, response codes etc. The most important thing here will be supporting JSON as the primary content type this will be the easiest for him/her to consume and work with by far.
您的 Java 人员也需要手册，但理论上他们可以为您发送/使用的资源的任何 XML 表示提供示例 XSD(假设他们将请求作为内容类型:应用程序/xml").这可能帮助他们构建代理类等.JSON 到 Java 和 .NET 转换器可在线获取，并且根据您手册中的示例资源，他们应该能够使用这些类型的服务之一快速创建代理.从 JSON 生成 Java 类?.
Your Java guy would also want the manual, but also in theory they could be given example XSD for any XML representations of the resources you send/consume (assuming they make the request as "Content-Type: appplication/xml"). This may help them build proxy classes etc. JSON to Java and .NET converters are available online and given the example resources in your manual they should simply be able to use one of these types of services to quickly create proxies. Generate Java class from JSON?.
如果您绝对必须具有自动发现、自动代理生成等功能，那么您可能需要提供两者 REST 和 SOAP(使用 WSDL)端点的选择 - 此处的相关问题:ReST 代理对象生成器.
If you absolutely must have auto discovery, auto proxy generation etc then you may need to offer a choice of both REST and SOAP (with WSDL) endpoints - relevant question here: ReST Proxy Object Generator.
这篇关于ASP.NET web api:记录/指定服务的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！
