1. Introduce Swagger3 dependency in pom file
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-boot-starter</artifactId>
<version>3.0.0</version>
</dependency>
2. Write Swagger3Config configuration class
package com.infoshare.config;
import io.swagger.annotations.ApiOperation;
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.oas.annotations.EnableOpenApi;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
//@EnableSwagger2 是 swagger2.0版本的注解
//swagger在3.0之后换成了@EnableOpenApi
@Configuration
@EnableOpenApi
public class Swagger3Config {
@Bean
public Docket createRestApi(){
return new Docket(DocumentationType.OAS_30)
.apiInfo(apiInfo())
.select()
.apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
.paths(PathSelectors.any())
.build();
}
private ApiInfo apiInfo(){
return new ApiInfoBuilder()
.title("Swagger3接口文档")
.description("适用于前后端分离统一的接口文档")
.version("1.0")
.build();
}
}
3.Swagger3.0 commonly used annotations
@Api: Used on the requested class, it means the description of the class
tags="The annotation that can be seen on the UI interface to explain the function of the class"
value="This parameter is meaningless, and it is also seen on the UI interface. So there is no need to configure"@ApiOperation: Used on the requested method to explain the purpose and function of the
method value="Describe the purpose and function of the
method " notes="Remarks on the method"@ApiImplicitParams: Used in the request method to indicate a set of parameter descriptions
@ApiImplicitParam: Used in the @ApiImplicitParams annotation to specify all aspects of a request parameter
name: parameter name
value: Chinese character description and explanation of the
parameter required: whether the parameter must be passed
paramType: Where to put the parameter
· header --> get request parameter: @RequestHeader
· query --> get request parameter: @RequestParam
· path (for restful interface) --> get request parameter: @PathVariable
· div (Not commonly used)
· form (not commonly used)
dataType: parameter type, default String, other values dataType="Integer"
defaultValue: default value of the parameter@ApiResponses: used in the request method to represent a set of responses
@ApiResponse: used in @ApiResponses, generally used to express an incorrect response message
code: number, such as 400
message: information, such as "request parameters are not filled in"
response: the class that threw the exception@ApiModel: Used on the response class to indicate a message that returns the response data (this is generally used in scenarios such as @RequestBody when the post is created, when the
request parameters cannot be described using the @ApiImplicitParam annotation)
@ApiModelProperty: Use On attributes, describe the attributes of the response class
4. The Controller layer uses Swagger3 annotation example
package com.infoshare.controller;
import com.infoshare.service.IUserService;
import com.infoshare.util.SendMailUtil;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import org.springframework.scheduling.annotation.Async;
import javax.annotation.Resource;
import javax.servlet.http.HttpSession;
/**
* @author: RJC
* @time: 2020/9/12
*/
@Api(tags = "用户信息处理")
@RestController
@RequestMapping("/user")
public class UserController {
@Resource(name = "userServiceImpl")
private IUserService userService;
@Resource(name = "sendMailUtil")
private SendMailUtil sendMailUtil;
private final static int AUTH_CODE_VALID_TIME = 600; //验证码失效时间为 10 min
/**
* 异步获得验证码的接口
* 验证码存储到 Session 里面
* @param mail 邮箱
* @return authCode_
*/
@ApiOperation("用户获得注册验证码")
@Async
@GetMapping("/getAuthCode")
public String getAuthCode(@RequestParam(name = "mail") String mail,
HttpSession session){
String authCode_ = sendMailUtil.sendMailAndGetAuthCode(mail);
session.setAttribute("mail",authCode_);
session.setMaxInactiveInterval(AUTH_CODE_VALID_TIME); //设置验证码失效时间为10min
return authCode_;
}
}
5. Access the Swagger3 interface documentation interface
The access path of Swagger is changed from port/swagger-ui.html to port/swagger-ui/ or port/swagger-ui/index.html
. Choose one of the two access methods
localhost:8080/swagger-ui/
localhost:8080/swagger-ui/index.html
6. Swagger3 interface document interface display
