En el desarrollo de la separación de front-end y back-end, el back-end necesita proporcionar documentación de interfaz API para el front-end, que es un paso muy importante. Sin embargo, la escritura y actualización de los documentos de la interfaz también lleva mucho tiempo durante el proceso de desarrollo, especialmente el contenido de algunos parámetros, es fácil que el personal de la interfaz no utilice la interfaz debido a una escritura incorrecta. Swagger nació para resolver este problema. Durante el proceso de desarrollo, los documentos API se generan automáticamente de acuerdo con los parámetros configurados por los desarrolladores de back-end. Este artículo trata sobre las funciones básicas de usar este complemento en el proyecto Springboot.
Uno, Swagger está preocupado por la solución.
| anotación | Introducción |
|---|---|
| @Api | @Api se usa en una clase para ilustrar el papel de la clase. Puede marcar una clase de controlador como un recurso de documento Swagger |
| @ApiParam | Descripción de los parámetros utilizados para los métodos en Controller |
| @@ ApiOperation | Utilizado en el método en el controlador, explique el papel del método, la definición de cada interfaz |
| @ApiImplicitParam y @ApiImplicitParams | Utilizado en el método, para explicar los parámetros de solicitud individuales |
| @ApiModel | Usado para campos, indicando la descripción de los atributos del modelo. |
| @ApiModelProperty | Indica la descripción de la clase, que se utiliza para describir la recepción del parámetro en la clase de entidad. |
| @ApiResponse y @ApiResponses | @ApiResponse se usa en el método para explicar cierta información de la respuesta de la interfaz; @ApiResponses ensambla múltiples @ApiResponse |
Aquí hay una breve introducción. Para obtener más detalles, consulte el uso específico en el proyecto springboot a continuación.
En segundo lugar, la aplicación real en el proyecto springboot
(1) citó la dependencia
<!--Swagger依赖-->
<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>
Las dos dependencias introducidas aquí, la primera es la dependencia swagger. Después de introducir esta dependencia, puede ver el documento json devuelto, que es muy engorroso y complicado, y la legibilidad es extremadamente pobre. En este momento, se necesita una interfaz de usuario de pantalla Después de la introducción Es una dependencia de swagger mostrar la interfaz de usuario.
(2) Configurar arrogancia
@Configuration
@EnableSwagger2
@ComponentScan(basePackages = {
"com.example.api.controller" })
public class SwaggerConfig {
@Bean
public Docket buildDocket(){
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(buildApiInf())
.select()
.apis(RequestHandlerSelectors.basePackage("com.example.api.controller"))
.paths(PathSelectors.any())
.build();
}
private ApiInfo buildApiInf(){
return new ApiInfoBuilder()
//页面标题
.title("秒杀商城API文档")
//描述
.description("简单优雅的restful风格")
//创建人信息
.contact(new Contact("Curry-Kun","127.0.0.1:8080/","[email protected]"))
.termsOfServiceUrl("")
//版本号
.version("1.0")
.build();
}
}
(Tres) clase de interfaz de configuración y
capa de controlador de clase de entidad 1.
@RestController
@RequestMapping("/miaosha")
@Api(tags = "秒杀功能模块API")
public class MiaoshaAPIController {
@Autowired
ProductService productService;
@ApiImplicitParams({
@ApiImplicitParam(name = "pageNo",value = "页码数",required = true,dataType = "int",paramType = "query"),
@ApiImplicitParam(name = "pageSize",value = "展示条数",required = true,dataType = "int",paramType = "query")
})
/**
* 商品列表页api
* @request
* pageNo
* pageSize
* @response
* success
* fail
*
* */
@ApiOperation(value = "查询系统秒杀商品列表",notes = "采取分页的形式展示，需要pageNo页码数和pageSize每页展示条数")
@PostMapping(value = "product_list_api")
public ResponseResult product_list_api(@RequestParam(value = "pageNo",defaultValue = "1")int pageNo,
@RequestParam(value = "pageSize",defaultValue = "6")int pageSize,
User user){
if(user == null){
return ResponseResult.error(ResponseCode.NO_LOGIN);
}
PageInfo<ProductVo> page = productService.listProcuctVo(pageNo,pageSize);
return ResponseResult.success(page);
}
Esto implica el uso de @Api, @ApiImplicitParams, @ApiImplicitParam y @ApiOperation. En el código anterior, puede ver sus respectivos roles con más detalle.
Pensó que los resultados devueltos están todos encapsulados en ResponseResult, por lo que también debe anotarse
@Data
@ApiModel
public class ResponseResult<T> {
@ApiModelProperty(value = "返回状态码")
private int code;
@ApiModelProperty(value = "返回信息")
private String msg;
@ApiModelProperty(value = "返回数据")
private T data;
/**
* 不同的data数据类型对应不同的ResponseResult的类型
* */
/**
*return code message data 方法构造器
* */
public ResponseResult(ResponseCode rc,T data) {
this.data = data;
this.msg = rc.msg;
this.code = rc.id;
}
/**
* return code message
* */
public ResponseResult(ResponseCode rc) {
this.msg = rc.msg;
this.code = rc.id;
}
/**
* success
* */
public static <T> ResponseResult<T> success(T data){
return new ResponseResult<T>(ResponseCode.SERVER_SUCCESS,data);
}
/**
* error
* */
public static <T> ResponseResult<T> error(ResponseCode rc){
return new ResponseResult<T>(rc);
}
}
Esto implica el uso de anotaciones @ApiModel y @ApiModelProperty.
Inicie el proyecto y visite http: // {ip}: {port} /swagger-ui.html#/
(4) Optimice la interfaz de usuario La
interfaz de usuario anterior todavía no es muy conveniente de usar. También puede hacer una page. swagger-bootstrap-ui
1. Introduzca las dependencias
<dependency>
<groupId>com.github.xiaoymin</groupId>
<artifactId>swagger-bootstrap-ui</artifactId>
<version>1.6</version>
</dependency>
En este momento, debe visitar http: // {ip}: {port} /doc.html
y admitir la depuración en línea. Siempre que las anotaciones que escriba sean lo suficientemente detalladas, los principiantes podrán entenderlas.
3. ¿Qué debo hacer si no puedo encontrar la página de documentación de la API generada?
1. Error de no se puede acceder a la página: No hay mapeo para GET /swagger-ui.html
Esta situación ocurre porque el sistema pasa el swagger-ui.html solicitado como parámetro, lo que definitivamente causará un error. En este momento, debe modificar WebMvcConfigurer, interceptar swagger-ui.html y configurar la ubicación del archivo.
@Configuration
public class WebConfig implements WebMvcConfigurer{
@Override
public void addResourceHandlers(ResourceHandlerRegistry registry) {
registry.addResourceHandler("doc.html")//swagger-ui.html
.addResourceLocations("classpath:/META-INF/resources/");
registry.addResourceHandler("/webjars/**")
.addResourceLocations("classpath:/META-INF/resources/webjars/");
}
}
2. Aparece una página en blanco después de la visita. En
este caso, debe confirmar si la dependencia de IU utilizada por swagger se importa normalmente. Es probable que la dependencia no se importe, lo que hace que no se encuentre el archivo swagger-ui.html . Vaya a dom.xml para rastrearlo. O cuando vea las dependencias del sistema, si confirma que no hay dependencias de IU que necesita, puede degradar las dependencias para usar.