Creo que tanto el desarrollo front-end como el back-end han sido más o menos torturados por documentos de interfaz. El front-end a menudo se queja de que los documentos de interfaz proporcionados por el back-end son inconsistentes con la situación real. El back-end siente que escribir y mantener documentos de interfaz consumirá mucha energía y, a menudo, es demasiado tarde para actualizar. De hecho, ya sea que el front-end llame al back-end o el back-end llame al back-end, se espera un buen documento de interfaz.
Swagger integrado con SpringBoot puede describir claramente la interfaz a través de anotaciones muy simples y generar una página de documento visual.
La interfaz nativa de Swagger-ui es muy tosca, así que use knife4j-spring-ui en su lugar.
Navegación en este artículo
Una buena descripción del documento de la interfaz HTTP
- Escriba claramente la ruta de solicitud de la interfaz: QueryPath: / user / login
- Escriba claramente el tipo de método de solicitud de la interfaz: GET / POST / DELETE / PUT
- Escriba claramente el significado comercial de la interfaz y los escenarios de uso.
- Escriba claramente los parámetros de entrada de la interfaz: descripción del parámetro, tipo de parámetro, estructura del parámetro, si el parámetro debe pasarse
- Escriba claramente el tipo de retorno de la interfaz: estructura de datos devuelta, condiciones anormales
SpringBoot integra Swagger
Dependencia de introducción del proyecto
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.9.2</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.9.2</version>
</dependency>
<dependency>
<groupId>com.github.xiaoymin</groupId>
<artifactId>knife4j-spring-ui</artifactId>
<version>2.0.4</version>
</dependency>
SpringBoot sobre la configuración de Swagger
Simplemente pegue esta configuración de Swagger en el proyecto
@EnableSwagger2
@Configuration
public class SwaggerConfig implements WebMvcConfigurer {
@Bean
public Docket createRestApi() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
//这里改成自己的接口包名
.apis(RequestHandlerSelectors.basePackage("vip.codehome.springboot.tutorials.controller"))
.paths(PathSelectors.any())
.build();
}
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("SpringBoot教程接口文档")//标题
.description("使用swagger文档管理接口")//描述
.contact(new Contact("codehome", "", "[email protected]"))//作者信息
.version("1.0.0")//版本号
.build();
}
//解决doc.html，swagger-ui.html 404问题
@Override
public void addResourceHandlers(ResourceHandlerRegistry registry) {
registry.addResourceHandler("/**").addResourceLocations(
"classpath:/static/");
registry.addResourceHandler("swagger-ui.html").addResourceLocations(
"classpath:/META-INF/resources/");
registry.addResourceHandler("doc.html").addResourceLocations(
"classpath:/META-INF/resources/");
registry.addResourceHandler("/webjars/**").addResourceLocations(
"classpath:/META-INF/resources/webjars/");
}
}
Uso específico de Swagger
El papel de cada anotación
- @Api presenta el papel de la clase en la clase
- @ApiOperation pone el método para introducir el rol del método
- @ApiImplicitParam Introducción
- @ApiResponse presenta el estado de devolución
- @ApiModel, @ApiModelProperty Introducción El parámetro de entrada es un objeto y la devolución es una descripción del campo del objeto
Ejemplo de código
@RestController
@Api(tags = "Swagger注解测试类")
public class SwaggerUserController {
@ApiOperation(value = "这是一个echo接口")
@ApiImplicitParams({
@ApiImplicitParam(name = "msg",value = "请求的msg参数",required = true,paramType = "query"),
@ApiImplicitParam(name = "token",value = "请求的token",required = false,paramType ="header" )
})
@ApiResponses({
@ApiResponse(code=200,message = "请求成功"),
@ApiResponse(code=400,message="请求无权限")
})
@GetMapping("/echo")
public String echo(String msg,@RequestHeader(name = "token") String token){
return msg;
}
@PostMapping("/login")
public R<UserInfoVO> login(@RequestBody LoginDTO loginDTO){
UserInfoVO userInfoVO=new UserInfoVO();
userInfoVO.setNickname("编程之家");
userInfoVO.setToken("xxx");
return R.ok(userInfoVO);
}
}
@Data
@ApiModel
public class LoginDTO {
@ApiModelProperty(value = "用户账号或者邮箱")
String account;
@ApiModelProperty(value = "用户密码")
String passwd;
@ApiModelProperty(value = "用户密码")
String verifyCode;
}
Efecto de documento de interfaz
La visita aquí es http: // localhost: 8080 / doc.html, knife4j-spring-ui también tiene funciones más poderosas que las originales.
Mil millas comienzan con un solo paso. Aquí está el segundo artículo de la serie de tutoriales SpringBoot. Todos los códigos fuente del proyecto se pueden descargar en mi GitHub .
