Use Swagger2 to build API documentation in Spring boot

Programmers all want to be able to write technical documents, but they are reluctant to write documents. Because of the large number of interfaces, and full of business details, writing documents need to spend a lot of time to deal with formatting, the code changes also need to synchronize the document, often because of the project time is tight and so on causes the document lags behind the code, the interface caller's complaining sound. And programmers are best at "lazy" career, naturally there will be a variety of automatic document generation plug-in. Today is to introduce the swagger.

Next we use Swagger2 to build the API documentation in spring boot

Swagger is a simple but powerful API expression tool. It has the largest ecosystem of API tools on Earth, and thousands of developers, using almost all modern programming languages, are supporting and using swagger. Using the Swagger build API, we can get interactive documentation, an SDK for generating code automatically, and discovery features for the API.

Let's take a look at the specific effects:

You can see that the SWAGGER-UI is a controller classification, click on a controller can see the specific interface, and then click on the interface to see the interface information,:

We can see how the interface is requested, returns the data information, and the parameters that need to be passed. And the above data is automatically generated, even if the code has some modifications, the swagger document will automatically synchronize the changes. Very convenient.

• Building RESTful APIs

We need to have a RESTful API project before using SWAGGER2. Spring-boot creating RESTful API projects is very convenient and fast, here no longer describes how to create, you can refer to the project code

• Add Swagger2 Dependency

Include the following dependencies in the Pom.xml file.

1 <dependency> 2       <groupId>io.springfox</groupId> 3       <artifactid>springfox-swagger2 </artifactId> 4       <version>2.7.0</version> 5 </dependency> 6  <dependency> 7       <groupId>io.springfox</groupId> 8       <artifactid>springfox-swagger-ui</artifactid > 9       <version>2.7.0</version>10 </dependency>

• To create a Java configuration class for Swagger2

  @Configurationannotations indicate that it is a configuration class, and @EnableSwagger2 annotations turn on Swagger2. The Apiinfo () method configures some basic information. The Createrestapi () method specifies that the scanned package generates a document, by default all interfaces are displayed, and annotations can be used to @ApiIgnore identify the interface that is not displayed.

1/** 2  * Created by Yuicon on 2017/5/20.3  * Https://github.com/Yuicon 4  @EnableSwagger2 7 public CLA SS Swagger2 {8      @Bean10     public Docket Createrestapi () {One         return new . Select () 14// Specifies the directory path that the controller holds. APIs (requesthandlerselectors.basepackage ("Com.digag.web" }19 private Apiinfo Apiinfo () {return new Apiinfobuilder () 22//Document title ("Digag") 24//Document Description: Description ("Https://github . Com/yuicon ") termsofserviceurl (" Https://github.com/Yuicon ") version (" v1 " }30  

• Edit Document Interface Information

Let's look at an example:

1  @ApiOperation (value= "Create Entry") 2     @RequestMapping (method = requestmethod.post) 3     public Jsonresult<entry> Saveentry (@RequestBody @ApiParam (value = "Entry Object", required = True) Entry Entry, HttpServletRequest request) {4         return entryservice.create (entry, request); 5     }   

Swagger2 provides a number of annotations to enrich the interface information, commonly used are:

@ApiOperation: Use the method to describe the function of the method value: Indicates the interface name notes: Represents an interface detailed description @apiimplicitparams: Used to include a set of parameter descriptions on a method @apiimplicitparam: used in @apiimplicitparams annotations, Specify aspects of a request parameter Paramtype: parameter location header corresponding NOTE: @requestheaderquery corresponding NOTE: @requestparampath corresponding NOTE: @pathvariablebody corresponding NOTE: @ Requestbodyname: Parameter name datatype: argument type required: argument must pass Value: Description of parameter defaultvalue: Default value of parameter @apiresponses: used to represent a set of responses @apiresponse: used in @apire Sponses, typically used to express an incorrect response message code: Status Code message: Return custom Information response: class that throws an exception

• accessing documents

The default address for the Swagger2 document is /swagger-ui.html that native-developed access http://localhost:8080/swagger-ui.html can see the automatically generated documents.

Full results example to view project code

Reference information

Swagger Annotations Document
Swagger official website

Use Swagger2 to build API documentation in Spring boot