Article source: https://www.jianshu.com/p/8033ef83a8ed
Results as shown below:
Add Swagger2 dependency
pom.xmlAdd Swagger2 dependencies in
<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger2 --> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger2</artifactId> <version>2.7.0</version> </dependency> <!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger-ui --> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger-ui</artifactId> <version>2.7.0</version> </dependency>
Note: If it is version 2.2, there may be an error in the lower right corner, then please upgrade to version 2.7 to solve this problem.
Create Swagger2 configuration class
Application.javaCreate a configuration class for Swagger2 at the same level Swagger2.
@Configuration @EnableSwagger2 public class Swagger2 { @Bean public Docket createRestApi() { return new Docket(DocumentationType.SWAGGER_2) .apiInfo (apiInfo ()) .select() .apis(RequestHandlerSelectors.basePackage("com.jsoft.testspringboot.controller")) .paths(PathSelectors.any()) .build(); } private ApiInfo apiInfo() { return new ApiInfoBuilder() .title( "Building RESTful APIs with Swagger2 in Spring Boot" ) .description( "For more Spring Boot related articles, please follow: http://easonjim.com/" ) .termsOfServiceUrl("http://easonjim.com/") .contact("EasonJim") .version("1.0") .build(); } }
As shown in the code above, let Spring load the class configuration through @Configurationannotations. @EnableSwagger2Then enable Swagger2 through annotations.
After the Bean created by the createRestApifunction , the basic information used to create the Api (these basic information will be displayed on the documentation page). The function returns an instance to control which interfaces are exposed to Swagger for display. In this example, the specified package path is used to define the scan. Swagger will scan all the APIs defined by the Controller under the package and generate document content (except for the specified request).DocketapiInfo()select()ApiSelectorBuilder@ApiIgnore
Add document content
After completing the above configuration, the content of the document can actually be produced, but such a document is mainly for the request itself, and the description is mainly generated from the naming of functions, which is not user-friendly. We usually need to add some instructions to enrich the content of the document. . As shown below, we use @ApiOperationannotations to add descriptions to the API, and pass @ApiImplicitParamsand @ApiImplicitParamannotations to add descriptions to parameters.
@RestController @RequestMapping(value = "/users") // Through this configuration, the following mappings are all under /users, you can remove public class UserController { static Map<Long, User> users = Collections.synchronizedMap(new HashMap<Long, User>()); @ApiOperation(value = "Get user list", notes = "" ) @RequestMapping(value={""}, method=RequestMethod.GET) public List<User> getUserList() { List<User> r = new ArrayList<User>(users.values()); return r; } @ApiOperation(value = "Create user", notes = "Create user based on User object" ) @ApiImplicitParam(name = "user", value = "user detail entity user", required = true , dataType = "User" ) @RequestMapping(value="", method=RequestMethod.POST) public String postUser(@RequestBody User user) { users.put(user.getId(), user); return "success"; } @ApiOperation(value = "Get user details", notes = "Get user details according to the id of the url" ) @ApiImplicitParam(name = "id", value = "用户ID", required = true, dataType = "Long") @RequestMapping(value="/{id}", method=RequestMethod.GET) public User getUser(@PathVariable Long id) { return users.get(id); } @ApiOperation(value = "Update user details", notes = "Specify the update object according to the id of the url, and update the user details according to the passed user information" ) @ApiImplicitParams({ @ApiImplicitParam(name = "id", value = "用户ID", required = true, dataType = "Long"), @ApiImplicitParam(name = "user", value = "user detail entity user", required = true , dataType = "User" ) }) @RequestMapping(value="/{id}", method=RequestMethod.PUT) public String putUser(@PathVariable Long id, @RequestBody User user) { User u = users.get(id); u.setName(user.getName()); u.setAge(user.getAge()); users.put(id, u); return "success"; } @ApiOperation(value = "Delete user", notes = "Specify the delete object according to the id of the url" ) @ApiImplicitParam(name = "id", value = "用户ID", required = true, dataType = "Long") @RequestMapping(value="/{id}", method=RequestMethod.DELETE) public String deleteUser(@PathVariable Long id) { users.remove(id); return "success"; } }
After adding the above code, start the Spring Boot program and visit: http://localhost:8080/swagger-ui.html
. You can see the page of the RESTful API shown above. We can click on the specific API request again. Taking the POST type /users request as an example, we can find the Notes information we configured in the above code and the description information of the parameter user, as shown in the following figure.
In the requested page above, we see that the user's Value is an input box? Yes, in addition to viewing interface functions, Swagger also provides debugging and testing functions. We can click on the Model Schema (yellow area: it indicates the user's data structure) on the right side of the figure above, and then there is a user object in the Value. , we only need to modify it slightly, click the “Try it out！”button below to complete a request call!
illustrate:
Swagger2 can be used not only for Spring Boot projects but also for Spring MVC. The configuration is basically the same.
Maven example:
https://github.com/easonjim/5_java_example/tree/master/springboottest/springboottest2
refer to:
http://www.jianshu.com/p/8033ef83a8ed (The above content is transferred from this article)
http://www.keep3yue.com/461.html
https://springframework.guru/spring-boot-restful-api-documentation-with-swagger-2/
https://dzone.com/articles/spring-boot-restful-api-documentation-with-swagger
https://my.oschina.net/zhaky/blog/864562（Spring MVC）