I. Introduction to Swagger2

1. Advantages of Swagger2

Integrate into Spring Boot to build a powerful RESTful API document. Besides interface document management, code modification and automatic update, swagger 2 also provides powerful page testing function to debug RESTful API.

2. Common notes of Swagger2

Api: decorate the whole class to describe the function of Controller
 ApiOperation: a method, or an interface, that describes a class
 ApiParam: single parameter description
 ApiModel: receiving parameters with objects
 ApiProperty: a field describing an object when receiving parameters with the object
 ApiResponse: HTTP response one of the descriptions
 ApiResponses: overall description of HTTP response
 ApiIgnore: use this annotation to ignore this API
 ApiError: information returned when an error occurs
 ApiImplicitParam: a request parameter
 Apiimplicit params: multiple request parameters

II. Integration with SpringBoot2.0

1. Core dependence

spring-boot: 2.1.3.RELEASE
swagger: 2.6.1

2. Swagger2 configuration

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
/**
 * Swagger configuration file
 */
@Configuration
public class SwaggerConfig {
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.swagger.two"))
                .paths(PathSelectors.any())
                .build();
    }
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("SpringBoot utilize Swagger structure API File")
                .description("Use RestFul style, Founder: smile at cicada")
                .termsOfServiceUrl("https://github.com/cicadasmile")
                .version("version 1.0")
                .build();
    }
}

3. Add notes to startup class

@EnableSwagger2
@SpringBootApplication
public class SwaggerApplication {
    public static void main(String[] args) {
        SpringApplication.run(SwaggerApplication.class,args) ;
    }
}

4. Starting effect drawing

III. add, delete, change and check cases

1. Add users

(1) code block

@ApiOperation(value="Add user", notes="Create new users")
@ApiImplicitParam(name = "user", value = "User detailed entity user", required = true, dataType = "User")
@RequestMapping(value = "/addUser", method = RequestMethod.POST)
public ResponseEntity<JsonResult> addUser (@RequestBody User user){
    JsonResult result = new JsonResult();
    try {
        users.put(user.getId(), user);
        result.setResult(user.getId());
        result.setStatus("ok");
    } catch (Exception e) {
        result.setResult("Service exception");
        result.setStatus("500");
        e.printStackTrace();
    }
    return ResponseEntity.ok(result);
}

(2) renderings

2. User list

(1) code block

@ApiOperation(value="User list", notes="Query user list")
@RequestMapping(value = "/getUserList", method = RequestMethod.GET)
public ResponseEntity<JsonResult> getUserList (){
    JsonResult result = new JsonResult();
    try {
        List<User> userList = new ArrayList<>(users.values());
        result.setResult(userList);
        result.setStatus("200");
    } catch (Exception e) {
        result.setResult("Service exception");
        result.setStatus("500");
        e.printStackTrace();
    }
    return ResponseEntity.ok(result);
}

(2) renderings

3. User query

(1) code block

@ApiOperation(value="User query", notes="according to ID Query users")
@ApiImplicitParam(name = "id", value = "user ID", required = true, dataType = "Integer", paramType = "path")
@RequestMapping(value = "/getUserById/{id}", method = RequestMethod.GET)
public ResponseEntity<JsonResult> getUserById (@PathVariable(value = "id") Integer id){
    JsonResult result = new JsonResult();
    try {
        User user = users.get(id);
        result.setResult(user);
        result.setStatus("200");
    } catch (Exception e) {
        result.setResult("Service exception");
        result.setStatus("500");
        e.printStackTrace();
    }
    return ResponseEntity.ok(result);
}

(2) renderings

4. Update users

(1) code block

@ApiOperation(value="Update user", notes="according to Id Update user information")
@ApiImplicitParams({
        @ApiImplicitParam(name = "id", value = "user ID", required = true, dataType = "Long",paramType = "path"),
        @ApiImplicitParam(name = "user", value = "User object user", required = true, dataType = "User")
})
@RequestMapping(value = "/updateById/{id}", method = RequestMethod.PUT)
public ResponseEntity<JsonResult> updateById (@PathVariable("id") Integer id, @RequestBody User user){
    JsonResult result = new JsonResult();
    try {
        User user1 = users.get(id);
        user1.setUsername(user.getUsername());
        user1.setAge(user.getAge());
        users.put(id, user1);
        result.setResult(user1);
        result.setStatus("ok");
    } catch (Exception e) {
        result.setResult("Service exception");
        result.setStatus("500");
        e.printStackTrace();
    }
    return ResponseEntity.ok(result);
}

(2) renderings

5. Delete user

(1) code block

@ApiOperation(value="delete user", notes="according to id Delete specified user")
@ApiImplicitParam(name = "id", value = "user ID", required = true, dataType = "Long", paramType = "path")
@RequestMapping(value = "/deleteById/{id}", method = RequestMethod.DELETE)
public ResponseEntity<JsonResult> deleteById (@PathVariable(value = "id") Integer id){
    JsonResult result = new JsonResult();
    try {
        users.remove(id);
        result.setResult(id);
        result.setStatus("ok");
    } catch (Exception e) {
        result.setResult("Service exception");
        result.setStatus("500");
        e.printStackTrace();
    }
    return ResponseEntity.ok(result);
}

(2) renderings

IV. source code

GitHub address: cicada smile
https://github.com/cicadasmile/middle-ware-parent
 Code cloud address: smile at cicada
https://gitee.com/cicadasmile/middle-ware-parent