SpringBoot study notes: Swagger implement document management

SpringBoot study notes: Swagger implement document management

Swagger

　　Swagger is a complete specification and framework for generating, description, and visualization calls for RESTful Web services . Swagger's goal is to define a standard REST API and language-independent interface, you can let the computer and have no need to access the source code, documents, or monitoring network traffic can discover and understand the services capabilities .

 

Swagger integrated document management API

Project Integration Swagger

　　The first is to add dependent swagger of:

<!--swagger-spring-boot-starter -->
<dependency>
    <groupId>com.spring4all</groupId>
    <artifactId>swagger-spring-boot-starter</artifactId>
    <version>1.9.0.RELEASE</version>
</dependency>

　　Then, add @ EnableSwagger2Doc annotation startup class open Swagger, as follows:

@EnableSwagger2Doc
@SpringBootApplication
public class Application {

    public static void main(String[] args) {
        SpringApplication.run(CodeHelperApplication.class, args);
    }
}

Use Swagger to generate documentation

　　Swagger is generated by the corresponding API annotations, we need to add an interface on annotations to describe the various interfaces, such as

    @ApiOperation(value = " 查找城镇列表 ")
    @ApiResponses({@ApiResponse(code = 200,message = "OK",response = String.class)})
    @RequestMapping(value = "getTownInfoList.do", method = RequestMethod.POST)
    public List<String> getTownInfoList() {
        try {
            return studentMapper.getListGroup("stu_town");
        } catch (Exception e) {
            e.printStackTrace();
        }
        return null;
    }

　　Here we use the two notes:

• @ApiOperation used in the method, the operation of the method, the interface add notes attribute information may be described in detail.
• @ApiResponses used in the method, some information about the interface in response to the instructions; @ApiResponses encapsulates plurality @ApiResponse, to set different information in response to a different response code.

 

Online test interface

　　By  port / swagger-ui.html: server address to access Swagger service, its interface is as follows:

　　

　　Find a way just described, you can view the details of the interface, and try interface calls.　　

　　

 

Swagger comment

　　This section describes some of the notes generated common interface document, introduced above will not say

@Api

　　With the class, the role of the class described.

@Api (tags = { "student information Interface"}) 
@RestController 
public class StudentController { 
  ...   
}

@ApiModel

　　With the class, the class represents the parameters will be described.

@ApiModel(value = "com.ms.qiandao.model.StudentModel",description = "新增用户参数")
public class StudentModel {
    private Integer stu_id;
    private String stu_name;
    private String stu_sex;
    ...  
}

@ApiModedlProperty

　　Used in the field, represents a parameter field in a class will be described.

@ApiModel (value = "com.ms.qiandao.model.StudentModel", description = " Add User Parameters") 
public class StudentModel { 
    @ApiModelProperty (value = "student ID") 
    Private Integer stu_id; 
    @ApiModelProperty (value = " student name ") 
    Private String stu_name; 
    @ApiModelProperty (value =" student sex ") 
    Private String stu_sex; 
    ...   
}

@ApiParam

　　Controller for process parameters will be described.

@RequestMapping("cancel.do")
public RegisterCode getById(@ApiParam(value = "学生id",required = true) Integer id) {
   ...
}

@ApilmplicitParam and @ApilmplicitParams

　　For the method, illustrated as a separate request parameters, and @ApiParam similar, but is written in the above methods .

 

Reference material

• "Spring Cloud micro-Services, combat and practice"
• https://swagger.io/tools/swagger-ui/