ASP.NET的Web API：记录/指定服务 [英] ASP.NET web api: documenting/specifying a service
问题描述
我一直在看 asp.net网页API ，我喜欢实现实用的Web服务的简单
I've been looking at asp.net Web Api, and I like the simplicity of implementing a practical web service.
但是，我怎么能记录/指定这样实现的服务接口？例如，没有任何规范，我可以传递或生成一个Java的家伙，没有.NET的背景下，将让他轻松调用和使用的服务？我可以给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浏览器也可调用（即支持非crufy JSON）。
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网页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工装已经一起了很多。目前，我们正在评估扬鞭2.0 产卵，现在出到了的 Open API的倡议，肾错构瘤并的 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 是自动创建扬鞭（开放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:
- Web Application Desciption Language (WADL)
- Web Service Description Language 2.0 (WSDL 2.0)
我认为这是公平地说，没有这两种方法的上面有非常广泛采用，但WADL看起来像一个漂亮简洁的格式 - 一个快速的XSLT过顶，这可能是一个很好的可读格式。有很多在该apigee GitHub的网站
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.
在试图找到一个文档格式，适合我倾向于寻找灵感来自别人.... Apigee做了很多这方面的研究，并有此作为文档他们的API的这里或看看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.
的例子是基本符合劝线这里
如何自动文档：
使用.NET：有自动的生成的WebAPI帮助页面<一个很好的例子href=\"http://blogs.msdn.com/b/yaohuang1/archive/2012/05/21/asp-net-web-api-generating-a-web-api-help-page-using-apiexplorer.aspx\"相对=nofollow>此处。这个例子中的一个合乎逻辑的延伸可能得到它郊游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：新泽西是在Java社区用于自动生成WADL工具
Using Java: Jersey is a tool used in the Java community to generate WADL automatically.
什么与其他开发人员共享：
您的Javascript的家伙很可能希望像Facebook和apigee一个手册;给予资源，网址，响应codeS等的开发实例这里将支持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家伙也想手工，而且在理论上他们可以给予例如XSD为您发送/资源的任何XML重新presentations消耗（假设他们提出请求为内容类型：参加办法/ 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屋！
