The Swagger UI also provides annotations to further customize your documentation.
Listed here is some of the ;documentation to retrieve the todos service:
"/users/{name}/todos": {
"get": {
"tags": [
"todo-controller"
],
"summary": "retrieveTodos",
"operationId": "retrieveTodosUsingGET",
"consumes": [
"application/json"
],
"produces": [
"*/*"
],
As you can see, the documentation generated is very raw. There are a number of things we can improve in the documentation to describe the services better. Here are a couple of examples:
- Provide a better summary
- Add application/JSON to produces
Swagger provides annotations we can add to our RESTful services in order to customize the documentation. ;Let's add a few annotations to the controller in order to improve the documentation:
@ApiOperation(
value = "Retrieve all todos for a user by passing in his name",
notes = "A list of matching todos is returned. Current pagination
is not supported.",
response = Todo.class,
responseContainer = "List",
produces = "application/json")
@GetMapping("/users/{name}/todos")
public List<Todo> retrieveTodos(@PathVariable String name) {
return todoService.retrieveTodos(name);
}
A few important points to note are as follows:
- @ApiOperation(value = "Retrieve all todos for a user by passing in his name"): Produced in the documentation as a summary of the service
- notes = "A list of matching todos is returned. Current pagination is not supported.": Produced in the documentation as a description of the service
- produces = "application/json”: Customizes the produces section of the service documentation
Here is an extract of the documentation after the update:
get": {
"tags": [
"todo-controller"
],
"summary": "Retrieve all todos for a user by passing in his
name",
"description": "A list of matching todos is returned. Current
pagination is not supported.",
"operationId": "retrieveTodosUsingGET",
"consumes": [
"application/json"
],
"produces": [
"application/json",
"*/*"
],
Swagger provides a lot of other annotations to customize the documentation. Listed here are some of the important annotations:
- @Api: Marks a class as a Swagger resource
- @ApiModel: Provides additional information about Swagger models
- @ApiModelProperty: Adds and manipulates the data of a model property
- @ApiOperation: Describes an operation or an HTTP method against a specific path
- @ApiParam: Adds additional metadata for operation parameters
- @ApiResponse: Describes an example response of an operation
- @ApiResponses: A wrapper to allow a list of multiple ApiResponse objects.
- @Authorization: Declares an authorization scheme to be used on a resource or an operation
- @AuthorizationScope: Describes an OAuth 2 authorization scope
- @ResponseHeader: Represents a header that can be provided as part of the response
Swagger provides a few Swagger definition annotations that can be ;used to customize high-level information about a group of services--contacts, licensing, and other general information. Listed here are some of the important ones:
- @SwaggerDefinition: Definition-level properties to be added to the generated Swagger definition
- @Info: General metadata for a Swagger definition
- @Contact: ;Properties to describe the person to be contacted for a Swagger definition
- @License: Properties to describe the license for a Swagger definition