0 Prefacio
En el desarrollo de microservicios, el desarrollo colaborativo de front-end y back-end es esencial.Con el aumento en la cantidad de servicios e interfaces, la documentación de interfaz escrita a mano se ha convertido en una tarea, y muchos programadores también se resisten a esto. Al mismo tiempo, también necesitamos un lugar para administrar estas interfaces de manera unificada.
Un grupo de programadores perezosos se preguntó si podría haber una herramienta para generar automáticamente este documento de interfaz, luego otro grupo de programadores perezosos desarrolló la herramienta de generación automática de documentos de interfaz swagger
1. Introducción a la arrogancia
Swagger es esencialmente un servicio web para generar, describir y llamar a interfaces de estilo REST. Además de la documentación de la interfaz, swagger también admite pruebas en línea. Ingrese los valores de los parámetros directamente en la interfaz para probar
Ahora en producción real, knife4j que integra swagger se usa para administrar documentos de interfaz, pero para la coherencia de los puntos de conocimiento, primero aprendamos swagger, y knife4j se explicará más adelante.
2. Usar arrogancia
2.1 Introduciendo swagger en un solo servicio
1. Agregar dependencias de swagger al servicio
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.9.2</version>
</dependency>
<!-- swagger-ui -->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.9.2</version>
</dependency>
2. Cree el archivo de configuración de swagger SwaggerConfig
import io.swagger.annotations.Api;
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.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
/**
* @author whx
* @date 2022/4/16
*/
@EnableSwagger2
@Configuration
public class SwaggerConfig {
@Bean
public Docket createRestApi() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
// api过滤器，设置哪些接口会加载创建接口文档
// .apis(RequestHandlerSelectors.basePackage("com.xx.xx"))
.apis(RequestHandlerSelectors.withClassAnnotation(Api.class))
.apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
.paths(PathSelectors.any())
.build();
}
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("商品服务接口文档")
.description("商品服务接口文档说明：xxx")
.contact(new Contact("55555", "", "[email protected]"))
.version("1.0")
.build();
}
}
3. Agregue una descripción
a la clase de entidad Use anotaciones en las clases de entidad Use anotaciones @ApiModel
en los campos@ApiModelProperty
@Data
@ApiModel(value = "Product对象", description = "商品对象")
public class Product {
@ApiModelProperty(value = "主键")
private Long id;
@ApiModelProperty(value = "商品名称")
private String name;
@ApiModelProperty(value = "商品编号")
private String no;
@ApiModelProperty(value = "商品价格")
private Double price;
@ApiModelProperty(value = "创建时间")
private Date createTime;
}
4. Agregue una descripción
al controlador Agregue anotaciones a clases y @Apimétodos para agregar anotaciones@ApiOperation
@RestController
@AllArgsConstructor
@Api(value = "商品Controller", tags = "商品接口")
public class ProductController {
private final IProductService productService;
@ApiOperation(value = "列表", notes = "无参数")
@GetMapping("list")
public List<Product> list(){
return productService.list();
}
@ApiOperation(value = "保存", notes = "无参数")
@PostMapping("save")
public String save(){
Product product = new Product();
product.setId(555L);
product.setName("商品xxx");
product.setPrice(300.0);
product.setNo("SP001");
product.setCreateTime(new Date());
int i = 1/0;
return productService.save(product) ? "保存成功" : "保存失败";
}
}
5. Reinicie el servicio y visite localhost:9091/swagger-ui.html. Aquí, el número de puerto del servicio es 9091.
Haga clic en el controlador correspondiente para ver la interfaz en la capa de control y haga clic en la interfaz específica para ver la documentación detallada de la interfaz.
3. Anotaciones comunes
@Api：说明类的作用。作用位置Controller
tags="说明该类的作用，标签"
value="接口说明"
@ApiOperation：说明接口/方法的作用。作用位置：Controller方法
value="接口名"
notes="接口备注"
@ApiModel：说明实体类。作用位置：实体类
value="实体类名称"
description="实体类描述"
@ApiModelProperty：实体类字段说明。作用位置：实体类字段
value=“字段的中文说明”
name=“字段名”
notes=“字段备注”
required=“是否必填”
hidden=“是否隐藏，默认false，为true时在swagger中不显示”
dataType=“数据类型，可以设置为String,Integer等”
allowableValues=“允许值”
@ApiImplicitParams：用在Controller方法上，表示一组参数说明
@ApiImplicitParam：用在@ApiImplicitParams注解中，说明这个参数的各种信息
name=“参数名”
value=“参数的中文说明”
required=“参数是否比天”
paramType=“参数位置，比如如果参数来自header，那么其值为header”
· header: 请求头参数 @RequestHeader
· query: 普通请求参数 @RequestParam
· path：路径请求参数 @PathVariable
dataType：参数类型，默认String，其它值dataType="Integer"
defaultValue：参数的默认值
@ApiResponses：用在Controller方法上，表示一组响应
@ApiResponse：用在@ApiResponses中，一般用于表达一个错误的响应信息
code=“状态码，例如400”
message=“信息，例如‘请求参数没填好’”
response=”抛出异常的类“
Entonces, en este punto, nuestra configuración de swagger para un solo servicio está completa. ¿No es sencillo?
Sin embargo, ¿alguna vez ha pensado en una pregunta, si tengo varios otros servicios ahora, tendré que implementar los pasos anteriores en cada servicio?
Luego, cuando queremos acceder a los documentos de interfaz de diferentes servicios, tenemos que cambiar de puerto, lo cual es muy problemático. ¿Hay alguna forma de resumir los archivos de puerto de estos servicios en un solo servicio? Solo necesitamos acceder a un puerto para ver todos los servicios Documentación de la interfaz.
Al mismo tiempo, ¿todavía recuerda el concepto del que hablamos en el Capítulo 8 de que todos los archivos de configuración de nacosp están centralizados en una clase de interfaz para la configuración? Necesitamos reducir el trabajo repetitivo, entonces, ¿solo necesitamos configurar el archivo de configuración de swagger anterior una vez?
Luego, en el próximo número, comenzamos a configurar el verdadero springcloud + swagger
Sigue la cuenta oficial de Elasticsearch home para conocer más contenido nuevo
Blog de referencia
https://zhuanlan.zhihu.com/p/161947638