documentación de la interfaz swagger
-
- 1. Introducción a swagger
- En segundo lugar, springboot integra swagger
- Tres, configura swagger
- Cuarto, las anotaciones swagger se utilizan para describir interfaces y clases de entidad.
- 5. ¿Qué crees que es swagger solo puede proporcionar información de descripción de interfaz? Eh ~
- Seis, finalmente
1. Introducción a swagger
Separación delantera y trasera
Vue + springboot un conjunto de soluciones
Era de back-end: el front-end solo administra páginas estáticas; html ===> back-end. El motor de plantilla jsp ejb backend es la fuerza principal
La era de la separación de los extremos delantero y trasero:
- Back-end: capa de control de back-end, capa de servicio, capa de acceso a datos [equipo de back-end]
- Interfaz: capa de control de interfaz (enlace bidireccional), capa de visualización [equipo de interfaz]
- Datos de back-end falsificados, json. Ya existe, no se necesita backend y el proyecto completo aún puede ejecutarse.
- ¿Cómo interactúan los extremos delantero y trasero? ===> API json
- Extremos delantero y trasero relativamente independientes, débilmente acoplados
- Los front-end y back-end se pueden implementar en diferentes servidores.
La separación de los extremos delantero y trasero, un problema
- La integración de front-end y back-end y la depuración conjunta, el personal de front-end y back-end no puede hacerlo, "negociar en tiempo real, resolver lo antes posible", lo que eventualmente conduce a un brote concentrado de problemas
Solución:
-
Especifique el esquema [Esquema del plan]. Actualice la última API en tiempo real para reducir el riesgo de integración;
-
Primeros años: Desarrollar documentos de planes de Word;
-
Separación delantera y trasera:
- Interfaz de back-end de prueba de front-end: cartero
- ¡El back-end proporciona una interfaz y necesita actualizar las últimas noticias y cambios en tiempo real!
ha nacido la arrogancia
- Conocido como el marco de api más popular del mundo
- Herramienta de generación automática en línea de documentos de API Restful => el documento de API y la definición de API están sincronizados y actualizados
- Ejecutar directamente, probar la interfaz api en línea
- Soporta múltiples idiomas java, php, py ...
Sitio web oficial: https://swagger.io
Use swagger springbox en el proyecto
- swagger2
- ui
En segundo lugar, springboot integra swagger
confiar
-
Importar dependencias relacionadas
- springfox-swagger2
- springfox-swagger-ui
-
pom
<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger2 --> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger2</artifactId> <version>2.9.2</version> </dependency> <!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger-ui --> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger-ui</artifactId> <version>2.9.2</version> </dependency>
Escribe la interfaz helloworld
package cn.bitqian.swagger.controller;
import org.springframework.web.bind.annotation.*;
/**
* hello world
* @author echo lovely
* @date 2020/10/28 19:23
*/
@RestController
public class HelloController {
@RequestMapping(value = "/hello")
public String hello() {
return "hello";
}
}
Configurar swagger ==> clase de configuración de configuración
Swagger abierto, Enablexxx
@Configuration
@EnableSwagger2 // 开启swagger2
public class SwaggerConfig {
}
Prueba de funcionamiento
http: // localhost: 8080 / swagger-ui.html
Tres, configura swagger
Dígale al personal de transferencia qué hace la interfaz y describa la interfaz del controlador. También puede establecer permisos de acceso a la interfaz.
package cn.bitqian.swagger.config;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
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;
import java.util.ArrayList;
/**
* swagger配置类
* @author echo lovely
* @date 2020/10/28 19:35
*/
@Configuration
@EnableSwagger2 // 开启swagger2
public class SwaggerConfig {
// 文档的标题，和描述！作者的信息deng..
@Bean
public Docket docket() {
return new Docket(DocumentationType.SWAGGER_2).apiInfo(appInfo());
}
// api 信息 接口文档的头部信息描述
public ApiInfo appInfo() {
Contact contact = new Contact("bitqian", "http://example.com", "[email protected]");
return new ApiInfo("bitqian的swagger文档",
"用来描述此接口的功能，内容。",
"v1.0",
"http://example.cn", contact,
"Apache 2.0",
"http://www.apache.org/licenses/LICENSE-2.0",
new ArrayList());
}
}
interfaz de escaneo de configuración swagger
@Bean
public Docket docket() {
return new Docket(DocumentationType.SWAGGER_2).apiInfo(appInfo()).
select().
// RequestHandlerSelectors 配置要扫描的接口的方式
// basePackage 指定要扫描的包
// any() 扫描全部
// none() 不扫描
// withClassAnnotation(Controller.class) 扫描类上的注解, 生效
// withMethodAnnotation(RequestMapping.class) 扫描方法上的注解, 生效
apis(RequestHandlerSelectors.basePackage("cn.bitqian.swagger.controller")).
// paths(PathSelectors.ant("/bitqian/**")) 扫描指定的接口
// PathSelectors.regex("")
paths(PathSelectors.ant("/hello/**"))
.build();
}
¿Cómo empezar a pavonearse solo en el entorno de producción?
- Determinar si es un entorno de producción
- Inyectar habilitar
@Bean
public Docket docket(Environment environment) {
// 获取当前环境 是生产环境 启动swagger
boolean isProFlag = environment.acceptsProfiles(Profiles.of("pro"));
System.out.println("is dev environment....===========>" + isProFlag);
return new Docket(DocumentationType.SWAGGER_2).apiInfo(appInfo()).groupName("bitqian").
enable(isProFlag). // 是否启动swagger 如果为false，则不能在浏览器中使用swagger
select().
apis(RequestHandlerSelectors.basePackage("cn.bitqian.swagger.controller")).
// paths(PathSelectors.ant("/hello/**")).
build();
}
Configurar la agrupación de documentos api
- Cree múltiples expedientes y varias personas escriban diferentes interfaces
@Bean
public Docket docket1() {
return new Docket(DocumentationType.SWAGGER_2).groupName("bitqian666 group1");
}
@Bean
public Docket docket12() {
return new Docket(DocumentationType.SWAGGER_2).groupName("bitqian666 group2");
}
Cuarto, las anotaciones swagger se utilizan para describir interfaces y clases de entidad.
canta
package cn.bitqian.swagger.entity;
import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
/**
* 给实体类生成文档
* @author echo lovely
* @date 2020/10/29 21:09
*/
@ApiModel("user实体类")
public class User {
@ApiModelProperty("用户名")
public String username;
@ApiModelProperty("密码")
public String password;
public User() {
}
public User(String username, String password) {
this.username = username;
this.password = password;
}
}
controlador
package cn.bitqian.swagger.controller;
import cn.bitqian.swagger.entity.User;
import io.swagger.annotations.ApiOperation;
import io.swagger.annotations.ApiParam;
import org.springframework.web.bind.annotation.*;
/**
* hello world
* @author echo lovely
* @date 2020/10/28 19:23
*/
@RestController
public class HelloController {
@ApiOperation("get/post都可的hello接口")
@RequestMapping(value = "/hello")
public String hello() {
return "hello";
}
@ApiOperation("get的hello接口, 返回一个空 user")
@GetMapping(value = "/hello1")
public User hello1() {
return new User();
}
@ApiOperation("hello1 接口post way~")
@PostMapping(value = "/hello1")
public User hello1(@ApiParam("传递用户") User user) {
return user;
}
@ApiOperation("登录接口 post way~")
@PostMapping(value = "/login")
public String login(@ApiParam("登录用户名") @RequestParam("username") String username,
@ApiParam("登录密码") @RequestParam("password") String password) {
return "ok" + "{" + username + ", " + password + "}";
}
}
5. ¿Qué crees que es swagger solo puede proporcionar información de descripción de interfaz? Eh ~
Swagger puede probarlo
Pruébalo
Seis, finalmente
- Podemos agregar información de anotaciones a algunos atributos o interfaces más difíciles de entender a través de swagger
- Actualización en tiempo real de la documentación de la interfaz
- Se puede probar en línea
Swagger es una excelente herramienta, utilizada por casi todas las grandes empresas, más acorde con las necesidades del desarrollo iterativo.
[Nota] Cuando se lance oficialmente, ¡ciérrate! ! ! Por razones de seguridad. Y ahorre memoria en funcionamiento.