Introducción a Swagger
1. ¿Qué es Swagger?
Como desarrollo de un programa de back-end, hemos escrito varios proyectos de interfaz de back-end más o menos, ya sea escribiendo una interfaz de teléfono móvil o el proyecto actual de separación de front-end, el front-end y el back-end son desarrollados por diferentes ingenieros, entonces esto La comunicación entre ellos se conecta a través de documentos de interfaz. Pero a menudo hay muchos problemas. Los programadores de back-end piensan que se necesita demasiado tiempo y energía para escribir documentos de interfaz y mantenimiento. Front-end cree que los cambios y actualizaciones de documentos de interfaz no son oportunos, lo que genera problemas al llamar y viajar entre programas. ¿Puede simplificar la escritura de documentos de interfaz y generarlos directamente de forma automática? ¡Por supuesto! Así nació Swagger, una herramienta de generación automática online de documentos de interfaz.
Swagger es un marco estandarizado y completo para generar, describir, invocar y visualizar servicios Web de estilo RESTful. El objetivo general es hacer que el cliente y el sistema de archivos se actualicen a la misma velocidad que el servidor. Los métodos, parámetros y modelos de archivo están estrechamente integrados en el código del lado del servidor, lo que permite que la API siempre esté sincronizada. Swagger nunca ha sido tan fácil de implementar, administrar y utilizar potentes API.
2.Ventajas Swagger
El código cambia, la documentación cambia. Con solo una pequeña cantidad de anotaciones, Swagger puede generar automáticamente documentación API basada en el código, lo que garantiza la puntualidad de la documentación.
Idiomas cruzados, admite más de 40 idiomas.
Lo que Swagger UI presenta es un documento API interactivo. Podemos probar la llamada API directamente en la página del documento, eliminando la necesidad de preparar parámetros de llamada complejos.
También puede importar especificaciones de documentos en herramientas relacionadas (como Postman, SoapUI), y estas herramientas crearán automáticamente pruebas automatizadas para nosotros.
Integra Swagger en SpringBoot
1. Construcción del entorno básico
Primero construya un proyecto SpringBoot básico e importe el siguiente iniciador Swagger
<dependency> <groupId> io.springfox </groupId> <artifactId> springfox-boot-starter <artifactId> <version> 3.0.0 </version> </dependency>
Escribe un controlador para probar
// java 源码 大全 www.fhadmin.org
@RestController
public class HelloController {
@PostMapping (value = "/ hello")
public String hello () {
return "hola";
}
}
Escribir clase de configuración Swagger
@Configuration
@EnableOpenApi
public class SwaggerConfig {
}
Ejecute la dirección de entrada de inicio: http: // localhost: 8080 / swagger-ui / index.html
¡Puede ver la página de documentación de la interfaz Swagger, que indica que el entorno de configuración básica es exitoso!
Nota:
La dirección de la versión Swagger3.0 es http: // localhost: 8088 / swagger-ui / index.html, y la dirección a la que se accede en la versión 2.x es http: // localhost: 8088 / swagger-ui.html
2. Configurar Swagger
Para configurar Swagger, primero debe construir su Docketobjeto de instancia Bean SwaggerConfig y crear un Docket en la clase de configuración que acaba de crear
// java 源码 大全 www.fhadmin.org
@Bean
public Docket docket () {
return new Docket (DocumentationType.OAS_30)
.apiInfo (apiInfo ());
}
Docket(DocumentationType.OAS_30) , El parámetro que elegimos aquí es DocumentationType.OAS_30que esta es la versión del documento de interfaz de una instancia de Swagger. Aquí somos 3.0, así que elegimos usarlo OAS_30. Otros tipos son los siguientes, correspondientes a la versión histórica de Swagger.
DocumentationType final estático público SWAGGER_12 = new DocumentationType ("swagger", "1.2");
DocumentationType final estático público SWAGGER_2 = new DocumentationType ("swagger", "2.0");
Public static final DocumentationType OAS_30 = new DocumentationType ("openApi", "3.0");
La construcción de Docket requiere la creación de una ApiInfo instancia
// Código fuente completo de Java www.fhadmin.org
private ApiInfo apiInfo () {
// Información del autor
Contact contact = new Contact ("TIOXY", "https://www.cnblogs.com/tioxy/", "1369773052 @ qq. com ");
return new ApiInfo (
" Documento de interfaz de Tioxy ",
" Descripción del proyecto ",
" 1.0 ",
" https://www.cnblogs.com/tioxy/ ",
contacto,
" Apache 2.0 ",
" http: / /www.apache.org/licenses/LICENSE-2.0 ",
nueva ArrayList ());
}
ApiInfo La función principal es construir la información básica que se muestra en la página de nuestro documento de interfaz, que se muestra en la siguiente posición
3. Configure la interfaz de escaneo y el interruptor
Al crear Docket, select() configure la interfaz de escaneo a través de métodos. El código completo de Docket es el siguiente:
// Completar el código fuente de Java www.fhadmin.org
@Bean
public Docket docket (Entorno ambiental) {
// Establecer el entorno Swagger que se muestra
Profiles dev = Profiles.of ("dev");
// Obtener el entorno del proyecto
boolean flag = environment.acceptsProfiles (dev);
return new Docket (DocumentationType.OAS_30)
.apiInfo (apiInfo ())
// Configure la agrupación de documentos de Api.
groupName ("TIOXY")
// enable () ya sea para habilitar Swagger, el valor predeterminado es true
.enable (flag)
. select ()
// RequestHandlerSelectors, configura la forma de escanear la interfaz
// basePackage especifica el paquete a escanear
// any () escanea todas, todas las interfaces en el proyecto serán escaneadas
// ninguna () no escanea
// withClassAnnotation () escanea las anotaciones en la clase
// withMethodAnnotation () escanea las anotaciones en el método.
apis (RequestHandlerSelectors.basePackage ("com.tioxy.controller"))
// rutas () filtra una ruta
. rutas (PathSelectors. any ())
.build ();
}
groupName("TIOXY"): Representa el nombre de esta instancia de Docket, es decir, el nombre de la instancia seleccionado en la esquina superior derecha de la página del documento de la interfaz. En el desarrollo real, estamos desarrollando por varias personas, correspondientes a varias instancias de Docketenable(flag):enable()Si se habilita Swagger, el valor predeterminado es verdadero
Lo que usamos aquí es la configuración dinámica de si habilitar Swagger, Environment hasta obtener el nombre del entorno del proyecto que se está ejecutando en este momento, si es así dev, definir una bandera para establecer dinámicamente si habilitar
4. Configuración de la clase de entidad
Crear una nueva clase de entidad de usuario
@ApiModel ("entidad de usuario")
clase pública Usuario {
@ApiModelProperty ("Nombre de usuario")
nombre de usuario de cadena pública;
@ApiModelProperty ("Contraseña")
contraseña de cadena pública;
}
Siempre que esta entidad esté en el valor de retorno de la interfaz de solicitud (incluso si es genérica), se puede asignar al elemento de la entidad:
@RequestMapping ("/ getUser")
public User getUser () {
return new User ();
}
5. Notas comunes
También podemos agregar notas a la interfaz, de modo que podamos explicar la información de la interfaz en el documento de la interfaz, como la función de la interfaz, descripción de parámetros, etc., para la conveniencia de la persona que llama
| Anotación Swagger | Breve descripción |
|---|---|
| @Api (etiquetas = "descripción del módulo xxx") | Actuar sobre la clase del módulo |
| @ApiOperation ("descripción de la interfaz xxx") | Actuar sobre los métodos de interfaz |
| @ApiModel ("descripción de xxxPOJO") | Actuar sobre la clase del modelo: como VO, BO |
| @ApiModelProperty (valor = "descripción de propiedad xxx", oculto = verdadero) | Actuar sobre los métodos y propiedades de la clase, hidden se establece en true para ocultar la propiedad |
| @ApiParam ("descripción del parámetro xxx") | Actuar sobre parámetros, métodos y campos, similar a @ApiModelProperty |