Chapter 4 springboot + swagger and springbootswagger

Chapter 4 springboot + swagger and springbootswagger

NOTE: Refer

Http://www.jianshu.com/p/0465a2b837d2

 

Swagger is used to define API documentation.

Benefits:

• Frontend and backend separation Development
• API documentation is very clear
• You do not need to enter the browser URL to access the Controller during the test.
• The traditional method of testing input URLs is inconvenient for passing parameters in post requests (of course, browser plug-ins such as postman can be used)
• Simple Integration of spring-boot and swagger

1. Project Structure

As in the previous section, it has not changed.

2. pom. xml

Two jars are introduced.

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

3. Application. java

1 package com. xxx. firstboot; 2 3 import org. springframework. boot. springApplication; 4 import org. springframework. boot. autoconfigure. springBootApplication; 5 6 import springfox.doc umentation. swagger2.annotations. enableSwagger2; 7 8 @ SpringBootApplication // same as @ Configuration + @ EnableAutoConfiguration + @ ComponentScan 9 @ EnableSwagger2 // start swagger annotation 10 public class Application {11 12 public static void main (String [] args) {13 SpringApplication. run (Application. class, args); 14} 15 16}View Code

Note:

• Introduced an annotation @ EnableSwagger2 to start the swagger annotation. (Start this annotation to make the swagger annotation used in the controller take effect. The coverage scope is specified by the @ ComponentScan configuration. All controllers under the root path "com. xxx. firstboot" are specified by default)

4. UserController. java

1 package com. xxx. firstboot. web; 2 3 import org. springframework. beans. factory. annotation. autowired; 4 import org. springframework. web. bind. annotation. requestHeader; 5 import org. springframework. web. bind. annotation. requestMapping; 6 import org. springframework. web. bind. annotation. requestMethod; 7 import org. springframework. web. bind. annotation. requestParam; 8 import org. springframework. web. bind. annotation. restController; 9 10 import com. xxx. firstboot. domain. user; 11 import com. xxx. firstboot. service. userService; 12 13 import io. swagger. annotations. api; 14 import io. swagger. annotations. apiImplicitParam; 15 import io. swagger. annotations. apiImplicitParams; 16 import io. swagger. annotations. apiOperation; 17 import io. swagger. annotations. apiResponse; 18 import io. swagger. annotations. apiResponses; 19 20 @ RestController21 @ RequestMapping ("/user") 22 @ Api ("userController related api") 23 public class UserController {24 25 @ Autowired26 private UserService userService; 27 28 // @ Autowired29 // private MyRedisTemplate myRedisTemplate; 30 31 @ ApiOperation ("Get user information") 32 @ ApiImplicitParams ({33 @ ApiImplicitParam (paramType = "header ", name = "username", dataType = "String", required = true, value = "User name", defaultValue = "zhaojigang "), 34 @ ApiImplicitParam (paramType = "query", name = "password", dataType = "String", required = true, value = "User password", defaultValue = "wangna ") 35}) 36 @ ApiResponses ({37 @ ApiResponse (code = 400, message = "the request parameter is not set"), 38 @ ApiResponse (code = 404, message = "no request path or incorrect page Jump path") 39}) 40 @ RequestMapping (value = "/getUser", method = RequestMethod. GET) 41 public User getUser (@ RequestHeader ("username") String username, @ RequestParam ("password") String password) {42 return userService. getUser (username, password); 43} 44 45 // @ RequestMapping ("/testJedisCluster") 46 // public User testJedisCluster (@ RequestParam ("username") String username) {47 // String value = myRedisTemplate. get (MyConstants. USER_FORWARD_CACHE_PREFIX, username); 48 // if (StringUtils. isBlank (value) {49 // myRedisTemplate. set (MyConstants. USER_FORWARD_CACHE_PREFIX, username, JSON. toJSONString (getUser (); 50 // return null; 51 //} 52 // return JSON. parseObject (value, User. class); 53 //} 54 55}View Code

Note:

• @ Api: Used in a class to describe the role of this class.
• @ ApiOperation: describes the role of a method when it is used in a method.
• @ ApiImplicitParams: describes a set of parameters used in a method.
• @ ApiImplicitParam: Used in the @ ApiImplicitParams annotation to specify all aspects of a request parameter
  • ParamType: where the parameter is stored
    • Header --> request parameter acquisition: @ RequestHeader
    • Query --> request parameter acquisition: @ RequestParam
    • Path (for restful Interface) --> request parameter acquisition: @ PathVariable
    • Body (not commonly used)
    • Form (not commonly used)
  • Name: Parameter name
  • DataType: parameter type
  • Required: required or not
  • Value: the meaning of the parameter.
  • DefaultValue: Default Value of the Parameter
• @ ApiResponses: indicates a group of responses.
• @ ApiResponse: Used in @ ApiResponses. It is generally used to express an error response message.
  • Code: Number, such as 400
  • Message: information, for example, "the request parameter is not filled"
  • Response: The class that throws an exception

These are the most common annotations.

For more information, see:

Https://github.com/swagger-api/swagger-core/wiki/Annotations#apimodel

 

Test:

Start the service, enter "http: // localhost: 8080/swagger-ui.html" in the browser"

A red box at the top: @ Api

GET Red box: method = RequestMethod. GET

Red box on the right: @ ApiOperation

Parameter red box: @ ApiImplicitParams series annotations

Response messages red box: @ ApiResponses series annotations

Enter parameters and click "try it out! ", View the response content: