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.
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
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
@Configuration
annotations 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
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