{"id":32202,"date":"2014-10-29T22:00:25","date_gmt":"2014-10-29T20:00:25","guid":{"rendered":"http:\/\/www.javacodegeeks.com\/?p=32202"},"modified":"2014-10-28T22:53:41","modified_gmt":"2014-10-28T20:53:41","slug":"spring-rest-api-with-swagger-creating-documentation","status":"publish","type":"post","link":"https:\/\/www.javacodegeeks.com\/2014\/10\/spring-rest-api-with-swagger-creating-documentation.html","title":{"rendered":"Spring Rest API with Swagger \u2013 Creating documentation"},"content":{"rendered":"

The real key to making your REST API easy to use is good documentation. But even if your documentation is done well, you need to set your company processes right to publish it correctly and on time. Ensuring that stakeholders receive it on time is one thing, but you are also responsible for updates in both the API and documentation. Having this process done automatically provides easy way out of trouble, since your documentation is no longer static deliverable and becomes a living thing. In previous post, I discussed how to integrate Swagger with your Spring application with Jersey. Now it\u2019s time to show you how to create documentation and publish it for others to see.<\/p>\n

Before I get down to the actual documentation, lets start with a few notes on its form and properties. We will be using annotations to supply metadata to our API which answers question how. But what about why? On one hand we are supplying new annotations to already annotation ridden places like API endpoints or controllers (in case of integration with Spring MVC). But on the other, this approach has a standout advantage in binding release cycle of application, API and documentation in one delivery. Using this approach allows us to create and manage small cohesive units ensuring proper segmentation of documentation and its versioning as well.<\/p>\n

Creating endpoint documentation<\/h2>\n

Everything starts right on top of your endpoint. In order to make Swagger aware of your endpoint, you need to annotate your class with @Api<\/code> annotation. Basically, all you want to do here is name your endpoint and provide some description for your users. This is exactly what I am doing in the following code snippet. If you feel the need to go into more detail with your API documentation, check out @Api<\/code> annotation description below.<\/p>\n

package com.jakubstas.swagger.rest;\r\n\r\n\/**\r\n * REST endpoint for user manipulation.\r\n *\/\r\n@Api(value = \"users\", description = \"Endpoint for user management\")\r\n@Path(\"\/users\")\r\npublic class UsersEndpoint {\r\n    ...\r\n}<\/pre>\n
To verify the results just enter the URL from your basePath<\/code> variable followed by \/api-docs<\/code> into your browser. This is the place where resource listing for your APIs resides. You can expect something similar to\u00a0following snippet I received after annotating three of my endpoints and accessing\u00a0http:\/\/[hostname]:[port]\/SpringWithSwagger\/rest\/api-docs\/<\/code>:<\/p>\n
{\r\n    \"apiVersion\":\"1.0\",\r\n    \"swaggerVersion\":\"1.2\",\r\n    \"apis\":[\r\n        {\r\n            \"path\":\"\/users\",\r\n            \"description\":\"Endpoint for user management\"\r\n        },\r\n        {\r\n            \"path\":\"\/products\",\r\n            \"description\":\"Endpoint for product management\"\r\n        },\r\n        {\r\n            \"path\":\"\/employees\",\r\n            \"description\":\"Endpoint for employee listing\"\r\n        }\r\n    ]\r\n}<\/pre>\n
However, please note that in order for an API to appear in APIs listing you have to annotate at least one API method with Swagger annotations. If none\u00a0of your methods is\u00a0annotated\u00a0(or you haven\u2019t provided any methods yet), API documentation will not be processed and published.<\/p>\n
@Api annotation<\/h4>\n
Describes a top-level api. Classes with @Api<\/code> annotations will be included in the resource listing.<\/p>\n
Annotation parameters:<\/p>\n