ASP.NET web api:记录/指定服务

Question

我一直在关注asp.net Web Api,我喜欢实现实用Web服务的简单性.

但是,我如何记录/指定这样实现的服务的接口？例如,我是否可以传递或生成没有.NET背景的Java人员,以便让他轻松调用和使用服务？我能给javascript的家伙什么？

理想情况下,我喜欢SOAP/XSD的好处或类似的东西(很容易用很好的类型对象反序列化),同时保留了一个可以从Web浏览器调用的服务(即支持非十分JSON).

更新

值得注意的是,自从我最初发布这个问题以来,我发现了更自然地处理这个问题的ServiceStack ; 支持JSON,SOAP和WSDL开箱即用,为客户选择相同的服务.如果你真的想要SOAP + JSON,它可能是一个比ASP.NET Web Api更好的框架.

Answer 1

2016年3月更新

已经有一段时间了,因为这个问题得到了解答,并且用于记录任何Rest API的工具已经出现了很多.我们目前正在评估Swagger 2.0现在产生的Open Api Initiative,RAML和API Blueprint.

对于WebAPI项目,有一个工具Swashbuckle可以自动创建Swagger(Open API)格式文档.

用于记录REST服务的格式:

有一些尝试构建和标准化REST服务的描述:

• Web应用程序Desciption语言(WADL)
• Web服务描述语言2.0(WSDL 2.0)

我认为可以说上述两种方法都没有被广泛采用,但WADL确实看起来像一个简洁的格式 - 一个快速的XSLT顶部,它可能是一个很好的人类可读格式.有很多的一些著名的API在apigee GitHub的网站WADL的例子在这里.

当试图找到一个文档格式,适合我倾向于寻找"灵感"来自别人.... Apigee做了很多这方面的研究,并曾以此为文档,其API的一个是在这里还是一起来看看Facebook的社交图api 在这里.

这些例子基本上符合这里的建议

如何自动记录:

使用.NET:有自动的生成的WebAPI"帮助"页面一个很好的例子在这里.这个例子的逻辑扩展也可能是为了让它在WADL格式化版本中运行...

使用Java:Jersey是Java社区中用于自动生成WADL的工具.

与其他开发者分享的内容:

你的Javascript家伙很可能想要一本像Facebook和apigee这样的手册; 给出了资源,网址,响应代码等的开发示例.这里最重要的是支持JSON作为主要内容类型,这对他/她来说最容易消费和使用.

您的Java人员也需要手册,但理论上也可以为您发送/使用的资源的任何XML表示提供示例XSD(假设他们将请求作为"Content-Type:appplication/xml").这可以帮助他们构建代理类等.JSON到Java和.NET转换器可以在线获得,并且在手册中给出了示例资源,他们应该能够使用这些类型的服务之一来快速创建代理.从JSON生成Java类？.

如果你绝对必须有自动发现,自动生成代理等,那么你可能需要提供的选择既 REST和SOAP(使用WSDL)端点-相关的问题在这里:REST代理对象生成.

Answer 2

您可以使用IApiExplorer接口和ApiExplorer类来为Web Api服务创建帮助页面.此帮助页面将描述您的服务公开的REST方法,因此任何了解REST如何工作的开发人员都可以使用它(无论语言如何).请阅读以下链接了解详情和样本:

• ASP.NET Web API:介绍IApiExplorer/ApiExplorer
• ASP.NET Web API:使用ApiExplorer生成Web API帮助页面
• 记录您的ASP.Net Web API