¡Nació el artefacto SpringDoc! La herramienta de documentación API más adecuada para SpringBoot está aquí
En el proyecto SpringBoot, he estado usando la biblioteca Swagger proporcionada por SpringFox. Fui al sitio web oficial y descubrí que no ha habido ninguna versión nueva durante casi dos años. Actualicé a SpringBoot 2.6.x hace unos días y descubrí que la compatibilidad de esta biblioteca está empeorando cada vez más. ¡Algunos atributos de anotación de uso común se han abandonado sin proporcionar reemplazos! Accidentalmente descubrí otra biblioteca Swagger, SpringDoc. La probé y fue muy buena. ¡Se la recomiendo a todos!
Introducción a SpringDoc
SpringDoc es una herramienta de generación de documentos API que se puede utilizar junto con SpringBoot. Está basado en OpenAPI 3 y actualmente tiene 1,7K estrellas en Github. Todavía soy muy diligente en la actualización y lanzamiento de versiones. Sí, ¡es una biblioteca Swagger más útil! Vale la pena mencionar que SpringDoc no solo admite proyectos Spring WebMvc, sino también proyectos Spring WebFlux e incluso proyectos Spring Rest y Spring Native. Aquí hay un diagrama de arquitectura de SpringDoc.
Uso
A continuación, presentaremos el uso de SpringDoc. Estamos utilizando el proyecto mall-tiny-swagger que anteriormente integraba SpringFox. Lo transformaré para usar SpringDoc.
Integración
Primero tenemos que integrar SpringDoc, simplemente agregue sus dependencias en pom.xml, funcionará de inmediato sin ninguna configuración.
lt;!--starter oficial de springdoc--gt;org.springdocspringdoc-openapi-ui1.6.6
Migración desde SpringFox
Echemos un vistazo primero Anotaciones Swagger de uso común, eche un vistazo a la diferencia entre SpringFox y SpringDoc. Después de todo, puede dominar rápidamente las nuevas tecnologías comparando las técnicas que ha aprendido;
A continuación, transformaremos las anotaciones utilizadas en el. Controlador anterior. Simplemente compárelo con la tabla anterior. ¡El atributo de descripción que ha estado abandonado durante mucho tiempo sin reemplazo en la anotación @Api finalmente es compatible!
/**
* Controlador de gestión de marca
* Creado por macro el 19/4/2019.
*/@Tag (nombre ="PmsBrandController", descripción ="Gestión de marca de producto")@Controller@RequestMapping("/brand")publicclassPmsBrandController{@AutowiredprivatePmsBrandService brandService; privatestaticfinalLogger LOGGER = LoggerFactory.getLogger(PmsBrandController.class);@Operation(summary="Get Lista de todas las marcas", descripción ="requiere iniciar sesión para acceder")@RequestMapping(value ="listAll", método = RequestMethod.GET)@ResponseBodypublicCommonResultgt; getBrandList() {returnCommonResult.success(brandService.listAllBrand()); }@ Operación (summary ="Agregar marca")@RequestMapping(valor ="/create", método = RequestMethod.POST)@ResponseBody@PreAuthorize("hasRole('ADMIN')")publicCommonResult createBrand(@RequestBodyPmsBrand pmsBrand) { CommonResult commonResult; int recuento = brandService.createBrand(pmsBrand); if(count ==1) { commonResult = CommonResult.success(pmsBrand); LOGGER.debug("createBrand éxito: {}", pmsBrand }else{ commonResult = CommonResult.failed); ( "La operación falló"); LOGGER.debug("createBrand falló: {}", pmsBrand }returncommonResult }@Operation(summ);
ary ="Actualizar la información de marca del id especificado")@RequestMapping(value ="/update/{id}", método = RequestMethod.POST)@ResponseBody@PreAuthorize("hasRole('ADMIN')")publicCommonResult updateBrand( @PathVariable( "id")Longid, @RequestBodyPmsBrand pmsBrandDto, resultado BindingResult) { CommonResult commonResult; int count = brandService.updateBrand(id, pmsBrandDto); .debug( "updateBrand éxito: {}", pmsBrandDto); }else{ commonResult = CommonResult.failed("La operación falló"); LOGGER.debug("updateBrand falló: {}", pmsBrandDto); (summary = "Eliminar la marca con la identificación especificada")@RequestMapping(value ="/delete/{id}", método = RequestMethod.GET)@ResponseBody@PreAuthorize("hasRole('ADMIN')")publicCommonResult deleteBrand( @PathVariable("id ")Longid) { int count = brandService.deleteBrand(id); if(count ==1) { LOGGER.debug("eliminar éxito de Brand: id={}", returnCommonResult.success(null); }else{ LOGGER.debug("Error en la eliminación de marca: id={}", id); returnCommonResult.failed("Error en la operación"); ="/lista", método = RequestMethod.GET)@ResponseBody@PreAuthorize("hasRole('ADMIN')")publicCommonResultgt; listBrand(@RequestParam(value ="pageNum", defaultValue ="1")@Parameter(descripción = "número de página") Número entero de página, @RequestParam (valor = "tamaño de página", valor predeterminado
="3")@Parameter(description ="Cantidad por página")Integer pageSize) { Lista brandList = brandService.listBrand(pageNum, pageSize); returnCommonResult.success(CommonPage.restPage(brandList) }@Operation(summary = "Obtenga los detalles de la marca de la identificación especificada")@RequestMapping(value = "/{id}", método = RequestMethod.GET)@ResponseBody@PreAuthorize("hasRole('ADMIN')")publicCommonResult brand(@PathVariable(" id" )Longid) {returnCommonResult.success(brandService.getBrand(id)); }}
A continuación, configure SpringDoc, use OpenAPI para configurar la información básica del documento, configure documentos API agrupados a través de GroupedOpenApi, SpringDoc admite directamente uso de rutas de interfaz para la configuración.
/**
* Configuración relacionada con el documento API SpringDoc
* Creado por macro el 4/3/2022.
*/ @ConfigurationpublicclassSpringDocConfig{@BeanpublicOpenAPImallTinyOpenAPI(){returnnewOpenAPI() .info(newInfo().title("Mall-Tiny API") .description("Demostración de SpringDoc API") .version("v1.0.0") .license(newLicense( ).name("Apache 2.0").url("/macrozheng/mall-learning"))) .externalDocs(newExternalDocumentation() .description("Conjunto completo de documentos del proyecto práctico de comercio electrónico SpringBoot (50K Star)") .url( "")); }@BeanpublicGroupedOpenApipublicApi(){returnGroupedOpenApi.builder() .group("marca") .pathsToMatch("/brand/**") .build(); builder() .group("admin") .pathsToMatch("/admin/**") .build() }}
Usado junto con SpringSecurity
Desde nuestro proyecto integra SpringSecurity. Para acceder a través del encabezado de autenticación JWT, también necesitamos configurar la ruta de la lista blanca de SpringDoc, principalmente la ruta de recursos de Swagger
/**
* Configuración de SpringSecurity <; /p >
* Creado por macro el 26/4/2018.
*/@Configuration@EnableWebSecurity@EnableGlobalMethodSecurity(prePostEnabled = true)la clase pública SecurityConfig extiende WebSecurityConfigurerAdapter {@Overrideprotected void configure(HttpSecurity / macrozheng/ mall-learning"))) .externalDocs(newExternalDocumentation() .description("Spring
Arranque el conjunto completo de documentos del centro comercial del proyecto de comercio electrónico real (50K Star)") .url("")) .addSecurityItem(newSecurityRequirement().addList(SECURITY_SCHEME_NAME)) .components(newComponents() .addSecuritySchemes(SECURITY_SCHEME_NAME, newSecurityScheme() .name( SECURITY_SCHEME_NAME) .type(SecurityScheme.Type.HTTP) .scheme("bearer") .bearerFormat("JWT"))); }}
Prueba
A continuación, inicie el proyecto Puede acceder a la interfaz Swagger Dirección de acceso: .macro.mall.tiny.controller# Configure las rutas de acceso de la interfaz que deben coincidir para generar el documento de interfaz: /brand/**, /admin/**.
Resumen
Dado que la biblioteca Swagger de SpringFox no ha lanzado una nueva versión durante mucho tiempo, migrar a SpringDoc es de hecho una mejor opción. Probé SpringDoc hoy y es realmente fácil de usar. Es casi lo mismo que conocía antes. El costo de aprendizaje es extremadamente bajo. Además, SpringDoc puede admitir proyectos como WebFlux y sus funciones son más poderosas. Los amigos que están un poco atascados en el uso de SpringFox. para migrar a él.
Materiales de referencia
Dirección del proyecto: /springdoc/springdoc-openapi
Documento oficial: /macrozheng/mall-learning/tree/master /mall-tiny-springdoc
/s/scityFhZp9BOJorZSdCG0w