Online API documentation tool swagger

     In project development, we often need to carry out joint debugging of front-end and back-end interfaces. In the past, we used api interface documents to describe interfaces. Once the interface is changed, we need to change the api documents, which is very inconvenient. Now we can use swagger to describe the interface. It is very convenient to view and call the interface online. If you don't know much about swagger, please see here: Learn about swagger in 5 minutes  .

     The following takes springboot as an example to configure and use swagger, as follows:

      1. Introduce pom 

<dependency>
	<groupId>io.springfox</groupId>
	<artifactId>springfox-swagger2</artifactId>
	<version>2.7.0</version>
</dependency>

<dependency>
	<groupId>io.springfox</groupId>
	<artifactId>springfox-swagger-ui</artifactId>
	<version>2.7.0</version>
</dependency>

   2. swagger configuration 

/**
 * @ClassName: SwaggerConfig  
 * @Description: swagger配置
 * @author ejshi  
 *@date Jan 31, 2018 7:53:38 PM  
 */
@SpringBootConfiguration
@EnableSwagger2
public class SwaggerConfig {
	
	@Bean
    public Docket api() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo (getApiInfo ())
                .select()
                .apis(RequestHandlerSelectors.basePackage("org.regulus.account.consumer.controller"))
                .paths(PathSelectors.any())
// .paths(Predicates.or(PathSelectors.regex("/[api|demo]/.*")))//Filtered interface
                .build();
    }

    private ApiInfo getApiInfo() {
        return new ApiInfoBuilder()
                .title("Api Documentation")
                .description("Api Documentation")
                .version("1.0.0")
                .license("Apache 2.0")
                .licenseUrl("http://www.apache.org/licenses/LICENSE-2.0")
                .contact(new Contact("shijun", "https://swagger.io/", "[email protected]"))
                .build();
    }
}

   3. Use swagger in the controller interface class   

@Api(value= "UserController",tags="user management" ,description="user management related functions API")
@RestController
public class UserController {
    
    @Reference
    private UserProvider userProvider;
    
    @ApiOperation(value = "Add" ,notes="Add data record")
    @PostMapping(path = "/user/add")
    public ResponseJson<Object> addUser(
    		@ApiParam("请求参数") @RequestBody @Validated(UserRequest.Add.class) UserRequest  userRequest){
        
        User user = BeanCopierUtil.invoke(userRequest, User.class);
        user.setId(StringUtil.uuid());
        
        userProvider.insertSelective(user);
        
    	return new ResponseJson<Object>(true, ResponseCodeEnum.SUCCESS);
    }
    
    @ApiOperation(value = "Query" ,notes="Query the corresponding data record, display in pagination")
    @GetMapping(path = "/user/listPage")
    public ResponseJson<List<UserResponse>> listPageUser(@ApiParam("请求数据") UserQuery userQuery){
        User user = BeanCopierUtil.invoke(userQuery, User.class);
        
        PageResultModel<User> pageResult = userProvider.selectWithPage(user, userQuery.getPageNum(), userQuery.getPageSize());
        
        List<UserResponse> userResponses = BeanCopierUtil.invokeList(pageResult.getDataList(), UserResponse.class);
        
        return new ResponseJson<List<UserResponse>>(true, ResponseCodeEnum.SUCCESS, userResponses,pageResult.getTotal());
    }
}

   4. Request parameter class, such as using swagger annotation in UserQuery 

@ApiModel
public class UserQuery {
	private static final long serialVersionUID = -2840366087876556526L;

	@ApiModelProperty("username")
	private String username;
		
	@ApiModelProperty("User state")
        private String userStatus;
	
	//Omit get/set method

}

   5. The swagger online api is shown in the figure

   

 

   6. Simple swagger annotation parameter explanation 

annotation	Common usage
@Api	Used on the controller class
@ApiOperation	Used on interface methods in controller
@ApiParam	for request parameters
@ApiModel	Used on request or response classes, such as UserQuery
@ApiModelProperty	Used on properties in @ApiModel annotated classes

   

   7. To view the instructions for using swagger annotations, click here , or here swagger official website