APIs should be beautiful. On the inside & the outside.
Swagger allows you to describe the structure of your APIs so that machines can read them.
The ability of APIs to describe their own structure is the root of all awesomeness in Swagger. Why is it so great? Well, by reading your API’s structure we can automatically build beautiful and interactive API documentation. We can also automatically generate client libraries for your API in many languages and explore other possibilities like automated testing.
Swagger does this by asking your API to return a JSON that contains a detailed description of your entire API. This JSON is essentially a resource listing of your API which adheres to Swagger Specification. The specification asks you to include information like:
So how do we get your APIs to return a swagger compliant resource listing?
Well, you can handcode it. But that really isn’t much fun.
How about if your server could automatically generate it for you? That is indeed possible and is supported for a number of technologies. The people who wrote swagger specification created support for a few (in bold below). The amazing swagger community has built support for a number of server side technologies to automate generation of swagger resource listing.
Click on ‘Swaggerize your service’ above for in depth tutorials on some of these technologies. A more complete listing of platforms and technolgies which work with Swagger is below:
|Java||JAX-RS (Jersey, Resteasy, CXF),
Spring using swagger-springmvc or swagger4spring-web
Express with swagger-jack
Standard HTTP/Express, Spec validation etc via Swagger Framework
|ColdFusion / CFML||swagger-docs-cfml|
|Misc||Alternative Swagger UI|