I’m building a solution hosted on Azure, and I would like to use ServiceStack as part of that solution (of course). In order to make this discoverable as part of the App Services Suite it would make sense to publish my ServiceStack Services as an API App . At first glance this seems like a really great fit for ServiceStack as a result of the Swagger-Support, but I am battling to understand how to wire this up (it requires a link to a Swagger metadata file and a jsonapp.json api definition). Is there an example of this somewhere (or can someone suggest some guidance)? All the MS tooling around this keeps installing WebAPI dependencies and making life generally difficult… and the documentation is quite lacking when it comes to 3rd party integrations (although the tuts all say that this is easily supported)…
The ServiceStack Swagger JSON service is available at /resources but I’m sure Azure API Services was only built to support a WebApi flavor.
What are you looking at using from Azure API?
Hi Demis,
I delved a little deeper into this and found that the Azure API Apps do support non-WepAPI REST service definitions. The metadata indicating the swagger “/resources” address is stored in an apiapp.json file, which I set up correctly.
Unfortunately the Azure API App consumer requires a SWAGGER 2.0 definition (and ServiceStack generates 1.1 definitions).
It sounds like something that could be addressed relatively easily to make ServiceStack a viable alternative to WebAPI in this space?
What do you think?
[RB]
PS: I found this article helpful in understanding the mechanics of setting this up . The second part details the requirements and deployment of the apiapp.json defintion.
I’ve just finished upgrading Swagger to 1.2 in this release that’s now on MyGet.
But Swagger has gone the way of large complicated specs and made rolling breaking changes where supporting Swagger v2 is effectively going to require a rewrite. The beauty of Swagger was that it started off as the minimal simple format needed in order generate a dynamic API UI, they’re now trying to turn it into the next WSDL, making the spec larger and more complicated and trying to overly spec every API detail.
I’m basically taking the wait-and-see approach whether Swagger v2.0 is going to gain any traction to make supporting it worthwhile. I dislike MS’s approach to code-gen’ing Rest API’s from a Swagger spec which is reminiscent of attempting the same thing with WSDL + code-gen proxies, other people have noticed this as well. Like most specs I expect MS to only support a WebApi flavor/convention where we’re going to end up in uncanny valley and a myriad of broken corner cases even for valid Swagger 2.0 specs - I’ll be more confident when I see other large web frameworks promoting using their Swagger 2.0 support with Azure API’s.
As it stands it’ll likely require less effort to add calling Live API’s directly from the /metadata pages which is my preferred approach since it will end up a more integrated UI that everyone can benefit from without registering an external dependency - whilst at the same time getting off the rolling Swagger spec train.
You can still add a feature request for it so we can measure the interest in it. Please include the use-case that you want to get from Azure API’s so we can see what real-world value you’re trying to get from it.
thanks for the explanation Demis…I’ll let you know if I hear of any developments in this space which you may find interesting…
@mythz We are now 14 months passed your “wait-and-see” comment. Do you have an update on your plans regarding swagger 2?
@mabead No updates, all our focus is on .NET Core support in the near term.
It would help if you could specify exactly why you want Swagger 2 support, is it the UI, Azure API Apps, AutoRest or something else? and why (i.e. what you need from the specific feature that’s missing in ServiceStack).
In the short term, our ultimate goal is to stop sharing binaries with the consumers of our API… exactly as “Add ServiceStack Reference” says:
Our goal with Native Types is to provide an alternative for sharing DTO
dlls, that can enable a better dev workflow for external clients who are
now able to generate (and update) Typed APIs for your Services from a
single remote url directly within their favorite IDE - reducing the
burden and effort required to consume ServiceStack Services whilst
benefiting from clients native language strong-typing feedback.
We tried using “Add ServiceStack Reference” and we had multiple problems. The code generated was at multiple occasions not functional. We therefore consider switching to AutoRest that is more focused on code generation and would hopefully provide better results.
AutoRest also has the advantage of not imposing ServiceStack to our clients. AutoRest imposes a dependecy on Microsoft.Rest.ClientRuntime that is more standard.
In the long run, we also consider using Azure API Apps. Swagger 2 would also be beneficial there. But this is less critical for now.
Add ServiceStack Reference imposes some limitations but these are discouraged practices that’s a source for a number of runtime issues when exposed beyond Service boundaries and should already be avoided. Other than the published limitations, if you have an issue please report them, we’d be happy to quickly resolve them. Add ServiceStack Reference is essentially the simplest way to enable and end-to-end typed API where the client interface is symmetrical to the server implementation (i.e. message in/out), that generates the least code-gen required whilst still being able to enable the ideal typed message-based API.
By contrast Swagger has little regard for backwards compatibility, is more complex with more moving parts - at the same time by mandating going through a spec that needs to support the lowest common API/language denominator we wouldn’t be able to provide rich integration where clients wouldn’t have access to metadata attributes and interfaces and wouldn’t be able to easily support high-level features like Encrypted Messaging, Service Gateway, Auto Batched Requests, streaming AutoQuery requests, etc.
All Add ServiceStack Reference generates are benign Typed DTOs, i.e. no behavior, no logic/implementations or RPC method stubs - essentially following the remote facade / gateway and DTO patterns which is less fragile, more versionable, less dependent on heavy tooling. They’re just POCOs which can easily be coped/created manually (without using Add SS Ref) using only a subset of the properties that clients are interested in. They’re also not coupled to any Service Clients or formats, you should easily be able to use the generated DTOs in any client, e.g. they also work well using HTTP Utils which is a generic thin high-level extension methods wrapping .NET’s HttpWebRequest.
Ultimately solutions that are dependent on complex, heavy tooling like SOAP/WS-*, .asmx/WCF Add ServiceStack Reference and AutoRest (though have yet to use it myself) are more fragile and usually yield more problems where slight API modifications can cause breaking changes in client applications as opposed to sending messages which are a lot more versionable and tolerant to changes.
If stopping sharing binaries is your short-term goal, the easiest and quickest way is to use Add ServiceStack Reference. If you can report any issues you have we should be able to quickly resolve them, if it’s due to a limitation, we should be able to suggest workarounds. We’ll still be considering implementing Swagger 2 after some R&D into time/feasibility, but it wont be until we’ve shipped first-class support for .NET Core which is our priority focus in the short-term.
Thanks for the feedback. When you say that ‘ServiceStack Reference imposes some limitations’, it makes me think that we are probably the root cause of the problem. We have inheritance in DTOs, Generics, interfaces, etc. We will look into it to have something more conventional.