Siga o projeto do deus louco SpringBoot para integrar o Swagger
Swagger de integração de projeto
alvo de aprendizagem:
-
Entenda o conceito e a função do Swagger
-
Domine a integração do Swagger no projeto para gerar documentação API automaticamente
Introdução ao Swagger
Separação frontal e traseira
-
Front end -> Camada de controle de front end, camada de visualização
-
Back-end -> Camada de controle de back-end, camada de serviço, camada de acesso a dados
-
O front-end e o back-end interagem por meio da API
-
As extremidades dianteira e traseira são relativamente independentes e fracamente acopladas
O problema
- Integração front-end e back-end, front-end ou back-end não podem ser "negociados a tempo e resolvidos o mais rápido possível", resultando em um foco concentrado de problemas
solução
- Primeiro defina
schema
[o esboço do plano] e acompanhe a API mais recente em tempo real para reduzir os riscos de integração
Arrogância
-
Conhecida como a estrutura de API mais popular do mundo
-
Gerador automático online de documento Restful Api => documento API e definição de API são atualizados de forma síncrona
-
Execute diretamente, teste a API online
-
Suporte a vários idiomas (como: Java, PHP, etc.)
-
Site oficial: https://swagger.io/
SpringBoot integra Swagger
SpringBoot integra Swagger => springfox , dois pacotes jar
-
Springfox-swagger2
-
swagger-springmvc
Use Swagger
Requisitos: jdk 1.8 +, caso contrário, o swagger2 não pode ser executado
degrau:
1. Crie um novo SpringBoot-web
projeto
2. Adicionar dependência Maven
<!-- 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>
3. Escreva HelloController
e teste para garantir uma operação bem-sucedida!
4. Para usar Swagger
, precisamos escrever uma classe SwaggerConfig
de configuração para configurarSwagger
@Configuration //配置类
@EnableSwagger2// 开启Swagger2的自动配置
public class SwaggerConfig {
}
5. Teste de acesso: a interface http://localhost:8080/swagger-ui.html
que pode ser vista swagger
;
Configurar Swagger
1. A Swagger
instância Bean
é Docket
, portanto, é configurada ao configurar a Docket
instância Swaggger
.
SwaggerConfig
@Bean //配置docket以配置Swagger具体参数
public Docket docket() {
return new Docket(DocumentationType.SWAGGER_2);
}
2. As apiInfo()
informações do documento podem ser configuradas por meio de propriedades
//配置文档信息
private ApiInfo apiInfo() {
Contact contact = new Contact("联系人名字", "http://xxx.xxx.com/联系人访问链接", "联系人邮箱");
return new ApiInfo(
"Swagger学习", // 标题
"学习演示如何配置Swagger", // 描述
"v1.0", // 版本
"http://terms.service.url/组织链接", // 组织链接
contact, // 联系人信息
"Apach 2.0 许可", // 许可
"许可链接", // 许可连接
new ArrayList<>()// 扩展
);
}
3. Docket
Associação de instânciaapiInfo()
@Bean
public Docket docket() {
return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo());
}
4, reinicie o projeto, acesse o http://localhost:8080/swagger-ui.html
efeito facial de teste ;
Configurar interface de varredura
1. Configure como fazer a varredura da interface Docket
por meio do select()
método durante a construção .
@Bean
public Docket docket() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()// 通过.select()方法,去配置扫描接口,RequestHandlerSelectors配置如何扫描接口
.apis(RequestHandlerSelectors.basePackage("com.kuang.swagger.controller"))
.build();
}
2. Reinicie o teste do projeto. Como configuramos para escanear a interface de acordo com o caminho do pacote, podemos ver apenas uma classe
3. Além de configurar a interface de varredura por meio do caminho do pacote, você também pode configurar outros métodos de varredura da interface. Aqui estão todos os métodos de configuração:
any() // 扫描所有,项目中的所有接口都会被扫描到
none() // 不扫描接口
// 通过方法上的注解扫描,如withMethodAnnotation(GetMapping.class)只扫描get请求
withMethodAnnotation(final Class<? extends Annotation> annotation)
// 通过类上的注解扫描,如.withClassAnnotation(Controller.class)只扫描有controller注解的类中的接口
withClassAnnotation(final Class<? extends Annotation> annotation)
basePackage(final String basePackage) // 根据包路径扫描接口
4. Além disso, também podemos configurar a filtragem de verificação da interface:
@Bean
public Docket docket() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()// 通过.select()方法,去配置扫描接口,RequestHandlerSelectors配置如何扫描接口
.apis(RequestHandlerSelectors.basePackage("com.kuang.swagger.controller"))
// 配置如何通过path过滤,即这里只扫描请求以/kuang开头的接口
.paths(PathSelectors.ant("/kuang/**"))
.build();
}
5. Os valores opcionais aqui são
any() // 任何请求都扫描
none() // 任何请求都不扫描
regex(final String pathRegex) // 通过正则表达式控制
ant(final String antPattern) // 通过ant()控制
Configurar o interruptor Swagger
1. Use o enable()
método para configurar se deseja habilitar ou não swagger
, se for false
, swagger
não estará acessível no navegador
@Bean
public Docket docket() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.enable(false) //配置是否启用Swagger,如果是false,在浏览器将无法访问
.select()// 通过.select()方法,去配置扫描接口,RequestHandlerSelectors配置如何扫描接口
.apis(RequestHandlerSelectors.basePackage("com.kuang.swagger.controller"))
// 配置如何通过path过滤,即这里只扫描请求以/kuang开头的接口
.paths(PathSelectors.ant("/kuang/**"))
.build();
}
2, quando o projeto é a configuração dinâmica test
, dev
o ambiente de exibição swagger
, prod
não é exibido?
@Bean
public Docket docket(Environment environment) {
// 设置要显示swagger的环境
Profiles of = Profiles.of("dev", "test");
// 判断当前是否处于该环境
// 通过 enable() 接收此参数判断是否要显示
boolean b = environment.acceptsProfiles(of);
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.enable(b) //配置是否启用Swagger,如果是false,在浏览器将无法访问
.select()// 通过.select()方法,去配置扫描接口,RequestHandlerSelectors配置如何扫描接口
.apis(RequestHandlerSelectors.basePackage("com.kuang.swagger.controller"))
// 配置如何通过path过滤,即这里只扫描请求以/kuang开头的接口
.paths(PathSelectors.ant("/kuang/**"))
.build();
}
Ambiente de Configuração
application.properties
spring.profiles.active=dev
application-dev.properties
server.port=8080
application-test.properties
server.port=8080
3. Você pode adicionar um arquivo de configuração dev ao projeto para verificar o efeito!
Configurar agrupamento de API
1. Se o agrupamento não estiver configurado, o padrão será default
. O groupName()
agrupamento pode ser configurado pelo método:
@Bean
public Docket docket(Environment environment) {
return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo())
.groupName("hello") // 配置分组
// 省略配置....
}
2. Reinicie o projeto para visualizar o grupo
3. Como configurar vários grupos? Para configurar vários grupos, você só precisa configurar vários grupos docket
:
@Bean
public Docket docket1(){
return new Docket(DocumentationType.SWAGGER_2).groupName("group1");
}
@Bean
public Docket docket2(){
return new Docket(DocumentationType.SWAGGER_2).groupName("group2");
}
@Bean
public Docket docket3(){
return new Docket(DocumentationType.SWAGGER_2).groupName("group3");
}
4. Reinicie o projeto para visualizar
Configuração de entidade
1. Crie uma nova classe de entidade
@ApiModel("用户实体")
public class User {
@ApiModelProperty("用户名")
public String username;
@ApiModelProperty("密码")
public String password;
}
2. Contanto que esta entidade esteja no valor de retorno da interface de solicitação (mesmo se for um genérico), ela pode ser mapeada para o item da entidade:
@RequestMapping("/getUser")
public User getUser(){
return new User();
}
3. Reinicie para ver o teste
Nota: Não é porque @ApiModel
essa anotação faz a entidade aparecer aqui, mas desde que a entidade apareça no valor de retorno do método de interface, ela será exibida aqui, @ApiModel
e @ApiModelProperty
essas duas anotações são apenas para adicionar anotações à entidade.
@ApiModel
Faça anotações na aula
@ApiModelProperty
Adicionar anotações aos atributos da classe
Notas comuns
Swagger
Todas as anotações são definidas no io.swagger.annotations
pacote
Alguns dos mais usados estão listados abaixo. Para aqueles não listados, consulte a explicação separadamente:
Anotação Swagger | Descrição breve |
---|---|
@Api(tags = "xxx模块说明") |
Atuar na classe do módulo |
@ApiOperation("xxx接口说明") |
Métodos de interface |
@ApiModel("xxxPOJO说明") |
Atue na classe do modelo: como VO, BO |
@ApiModelProperty(value = "xxx属性说明",hidden = true) |
Atua nos métodos e propriedades da classe, hidden é definido como true para ocultar a propriedade |
@ApiParam("xxx参数说明") |
Atua em parâmetros, métodos e campos semelhantes@ApiModelProperty |
Também podemos configurar algumas anotações para a interface solicitada
@ApiOperation("狂神的接口")
@PostMapping("/kuang")
@ResponseBody
public String kuang(@ApiParam("这个名字会被返回")String username){
return username;
}
Desta forma, você pode adicionar algumas informações de configuração a alguns atributos ou interfaces mais difíceis de entender, para que seja mais fácil de ler!
Comparado com a interface tradicional Postman
ou de Curl
teste de método, usá-lo é swagger
simplesmente uma operação tola. Não requer documentação adicional (bem escrito é um documento em si) e é menos sujeito a erros. Basta inserir os dados e clicar em Executar. Se você cooperar com a estrutura de automação, pode-se dizer que a operação humana é basicamente desnecessária.
Swagger
É uma ferramenta excelente. Agora, muitas pequenas e médias empresas de Internet na China estão usando-a. Em comparação com o método tradicional de exportação de Word
documentos de interface e teste, obviamente está mais de acordo com o mercado atual de desenvolvimento iterativo rápido. Claro, eu lembro a todos para lembrar de fechá-lo no ambiente Swagger
formal.Primeiro, por razões de segurança, ele também pode economizar memória de tempo de execução.
Teste o controlador swagger
HelloController
escrever
@ApiOperation(value = "/hello3", notes = "测试hello3")
@ApiImplicitParams({
@ApiImplicitParam(paramType = "query", name = "str", value = "str", dataType = "string")
, @ApiImplicitParam(paramType = "query", name = "age", value = "12", dataType = "Integer")})
@GetMapping(value = "/hello3")
public String hello3(String str, Integer age) {
String s = str + ":" + age;
return s;
}
- Referência
- teste de interface swagger
Expansão: outras peles
Podemos importar diferentes pacotes para obter diferentes definições de skin:
1. O acesso padrão http://localhost:8080/swagger-ui.html
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.9.2</version>
</dependency>
2. bootstrap-ui
Visitehttp://localhost:8080/doc.html
<!-- 引入swagger-bootstrap-ui包 /doc.html-->
<dependency>
<groupId>com.github.xiaoymin</groupId>
<artifactId>swagger-bootstrap-ui</artifactId>
<version>1.9.1</version>
</dependency>
3. Layui-ui
Visitehttp://localhost:8080/docs.html
<!-- 引入swagger-ui-layer包 /docs.html-->
<dependency>
<groupId>com.github.caspar-chen</groupId>
<artifactId>swagger-ui-layer</artifactId>
<version>1.1.3</version>
</dependency>
4. mg-ui
Visitehttp://localhost:8080/document.html
<!-- 引入swagger-ui-layer包 /document.html-->
<dependency>
<groupId>com.zyplayer</groupId>
<artifactId>swagger-mg-ui</artifactId>
<version>1.0.6</version>
</dependency>
Endereço de vídeo de apoio para a explicação do deus louco: https://www.bilibili.com/video/BV1Y441197Lw