Note: A newer revision of this blogpost for apiman 1.2.x can be found here. This version was written for apiman 1.1.x.
One of the weaknesses we’ve had in apiman until now is that service providers didn’t have any way to document how to consume their services. Well that has all changed with version 1.1.3.Final. Now you can upload a Swagger spec document for your service. If you do, consumers will be able to browse your service documentation directly in the apiman UI.
I think we can all agree that this is a welcome change and really improves the usability of the system, particularly from the perspective of the application developer (aka the service consumer).
Adding a Service Definition
As a service provider, the only thing you need to do is add a service definition to your service. This is simple - just navigate to the new “Definition” tab in your service. There you will be able to copy/paste or drag/drop a Swagger spec. Make sure you set the definition type to Swagger (JSON), and don’t forget to click Save!
What is a Swagger spec?
So maybe not everyone knows what Swagger is. Swagger is a way to formally describe a RESTful web service. A Swagger spec is a JSON document that describes everything about your RESTful API, including (but not limited to):
- API meta-data such as Name and Description
- Resource Paths and the Operations/Methods they support
- Input/Output types
For more information I recommend navigating to the Swagger Project.
How does this help my consumers?
Once you’ve got a Swagger spec created and added to your service, your service consumers will be able to browse live documentation right from the apiman UI. This information will be available via a new “View Service Definition” link available on the consumer’s “Service Details” page (the same page that consumers are shown when they have searched for a service). Here’s an example:
A service consumer can see that there is a service definition they can click on, which will give them a ton of information about how to use the service. In the future, we plan to allow consumers to do all sorts of interesting things with the Swagger spec. For example, we can help consumers generate a client SDK in a variety of languages. We can also allow them to simulate API calls right from the apiman UI - so they can see what to expect. But for right now, we simply show live documentation about the service as described by the Swagger spec definition:
As always, thanks for making it to the end of my ramblings!