Autor: macrozheng
Enlace original: https://mp.weixin.qq.com/s/XbBD0E136F72gI6OkVIZeA
Swagger, como herramienta de generación de documentos API, aunque la función es muy completa, todavía existen algunas deficiencias. Accidentalmente encontré que knife4j compensaba estas deficiencias y le daba más funciones a Swagger. Hoy hablaremos sobre cómo usarlo.
Introducción a knife4j
Knife4j es una implementación mejorada de la interfaz de usuario de springfox-swagger, que proporciona una experiencia de documentación de interfaz simple y poderosa para los desarrolladores de Java cuando usan Swagger. Knife4j sigue completamente el método de uso en springfox-swagger y tiene funciones mejoradas sobre esta base. Si ha usado Swagger, puede cambiar sin problemas a knife4j.
Inicio rápido
A continuación, presentaremos cómo usar knife4j en SpringBoot, ¡solo dos pasos!
- Aumente las dependencias relevantes de knife4j en pom.xml;
<!--整合Knife4j-->
<dependency>
<groupId>com.github.xiaoymin</groupId>
<artifactId>knife4j-spring-boot-starter</artifactId>
<version>2.0.4</version>
</dependency>- Agregue una anotación @ EnableKnife4j a Swagger2Config, que puede habilitar la función mejorada de knife4j;
/**
* Swagger2API文档的配置
*/
@Configuration
@EnableSwagger2
@EnableKnife4j
public class Swagger2Config {
}- Ejecute nuestra aplicación SpringBoot y visite la dirección del documento API para ver: http: // localhost: 8088 / doc.html
Caracteristicas
A continuación, comparemos Swagger y veamos cuál es la diferencia entre usar knife4j y eso.
Mejora de la función JSON
Siempre uso Swagger, pero el soporte JSON de Swagger no ha sido muy bueno. JSON no se puede plegar y es demasiado largo para verlo. Al pasar parámetros de formato JSON, no hay función de verificación de parámetros. Estos puntos débiles se han resuelto en knife4j.
- El conjunto de resultados devuelto admite el plegado para facilitar la visualización;
- El parámetro de solicitud tiene una función de verificación JSON.
Autenticación de inicio de sesión
knife4j también admite la adición de Token al encabezado para la autenticación de inicio de sesión.
- Primero agregue el Token devuelto por el inicio de sesión en la función Autorizar;
- Posteriormente, en cada interfaz, puede ver que la información del Token se ha transportado en el encabezado de la solicitud.
Documentos sin conexión
knife4j admite la exportación de documentos sin conexión para enviarlos fácilmente a otras personas y admite el formato Markdown.
- Seleccione directamente la gestión de documentos -> función de documento sin conexión, y luego elija descargar Markdown;
- Revisemos el documento sin conexión de Markdown exportado, que aún es muy detallado.
Parámetros globales
knife4j admite la configuración temporal de parámetros globales y admite dos tipos de consulta (formulario) y encabezado (encabezado de solicitud).
- Por ejemplo, si queremos agregar un parámetro appType a todos los encabezados de solicitud para distinguir si es una llamada de Android o iOS, podemos agregarlo en los parámetros globales;
- Cuando se llame a la interfaz en este momento, se incluirá el encabezado de solicitud appType.
Ignorar atributos de parámetros
A veces, la interfaz que creamos y modificamos usará el mismo objeto que el parámetro de solicitud, pero no necesitamos id cuando lo creamos, y necesitamos id cuando lo modificamos. En este momento, podemos ignorar el atributo id.
- Por ejemplo, en la interfaz de creación de productos aquí, la identificación, la cantidad del producto y las reseñas de productos se pueden generar sin pasar la interfaz de fondo. Puede usar la anotación @ApiOperationSupport proporcionada por knife4j para ignorar estos atributos;
/**
* 品牌管理Controller
* Created by macro on 2019/4/19.
*/
@Api(tags = "PmsBrandController", description = "商品品牌管理")
@Controller
@RequestMapping("/brand")
public class PmsBrandController {
@Autowired
private PmsBrandService brandService;
private static final Logger LOGGER = LoggerFactory.getLogger(PmsBrandController.class);
@ApiOperation("添加品牌")
@ApiOperationSupport(ignoreParameters = {"id","productCount","productCommentCount"})
@RequestMapping(value = "/create", method = RequestMethod.POST)
@ResponseBody
public CommonResult createBrand(@RequestBody PmsBrand pmsBrand) {
CommonResult commonResult; int count = brandService.createBrand(pmsBrand); if (count == 1) {
commonResult = CommonResult.success(pmsBrand); LOGGER.debug("createBrand success:{}", pmsBrand);
} else {
commonResult = CommonResult.failed("操作失败");
LOGGER.debug("createBrand failed:{}", pmsBrand);
} return commonResult;
}}- En este momento, al ver el documento de la interfaz, encontré que estos tres atributos han desaparecido, por lo que el desarrollo de front-end no sentirá que ha definido parámetros inútiles al ver el documento de la interfaz. ¿Es una buena función?
Referencia
Documento oficial: https://doc.xiaominfo.com/guide/
Dirección de origen del proyecto
https://github.com/macrozheng/mall-learning/tree/master/mall-tiny-knife4j