在Spring Boot中规范的使用Swagger进行接口测试

Diretório de artigos

O que é arrogância?
Por que usar o Swagger?
Preparação
configuração avançada
Uso do SwaggerUI
Problemas encontrados:

O que é arrogância?

Swagger é um conjunto de ferramentas de código aberto baseadas na especificação OpenAPI, que pode nos ajudar a projetar, construir, registrar e usar a API Rest. Swagger inclui principalmente três partes:

Editor Swagger: um editor baseado em navegador que podemos usar para escrever nossa documentação OpenAPI.
UI Swagger: apresentará a especificação OpenAPI que escrevemos como um documento de API interativo. Posteriormente usaremos um navegador para visualizar e operar nossa API Rest.
Swagger CodeGen: simplifica o processo de construção gerando stubs de servidor e SDKs de cliente para qualquer API definida pela especificação OpenAPI.

Simplificando, swagger é um software intermediário que pode gerar documentos de desenvolvimento de interface de acordo com o estilo resultante e oferece suporte a testes .

Por que usar o Swagger?

extremidade traseira:

Não há necessidade de escrever manualmente um grande número de parâmetros na interface do WiKi para evitar erros de escrita à mão
Baixa intrusividade no código, método de anotação completo, fácil desenvolvimento
A modificação do nome do parâmetro do método, o aumento e a diminuição dos parâmetros podem entrar em vigor diretamente, sem manutenção manual
Desvantagens: aumentar o custo de desenvolvimento e escrever uma interface para escrever outro conjunto de configuração de parâmetros

front-end:

O back-end só precisa definir a interface, e o documento será gerado automaticamente, e as funções e parâmetros da interface ficam claros à primeira vista
A depuração conjunta é conveniente. Se houver um problema, você pode testar diretamente a interface, verificar os parâmetros e o valor de retorno em tempo real e localizar rapidamente o problema no front-end ou no back-end.

teste:

Para algumas funções sem interface de interface front-end, você pode usá-la para testar a interface
A operação é simples, você pode operar sem conhecer o código específico

Preparação

Ambiente utilizado:
springboot: 2.7.8-SNAPSHOT
Java: 1.8
swagger: 2.9.2

		<dependency>
			<groupId>io.springfox</groupId>
			<artifactId>springfox-swagger2</artifactId>
			<version>2.9.2</version>
		</dependency>
		<dependency>
			<groupId>io.springfox</groupId>
			<artifactId>springfox-swagger-ui</artifactId>
			<version>2.9.2</version>
		</dependency>

criar projeto

insira a descrição da imagem aqui
adicionar dependências

<dependencies>
		<dependency>
			<groupId>org.springframework.boot</groupId>
			<artifactId>spring-boot-starter-web</artifactId>
		</dependency>

		<dependency>
			<groupId>org.springframework.boot</groupId>
			<artifactId>spring-boot-starter-test</artifactId>
			<scope>test</scope>
		</dependency>
		<dependency>
			<groupId>io.springfox</groupId>
			<artifactId>springfox-swagger2</artifactId>
			<version>2.9.2</version>
		</dependency>
		<dependency>
			<groupId>io.springfox</groupId>
			<artifactId>springfox-swagger-ui</artifactId>
			<version>2.9.2</version>
		</dependency>
	</dependencies>

interface de gravação

UserController fornece quatro interfaces para adicionar, excluir, modificar e verificar usuários, e TestController fornece uma interface de teste

Código-fonte pojo.user:

package com.example.demo.pojo;

import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;

/**
 * @Author 秋名山码神
 * @Date 2023/1/9
 * @Description
 */

@ApiModel("用户实体类")
public class User {
    
    
    @ApiModelProperty("用户名")
    private String username;
    @ApiModelProperty("密码")
    private String password;

    public String getUsername() {
    
    
        return username;
    }

    public void setUsername(String username) {
    
    
        this.username = username;
    }

    public String getPassword() {
    
    
        return password;
    }

    public void setPassword(String password) {
    
    
        this.password = password;
    }
}

Código-fonte do UserController:

package com.example.demo.controller;

import com.example.demo.pojo.User;
import org.springframework.web.bind.annotation.*;

/**
 * @Author 秋名山码神
 * @Date 2023/1/9
 * @Description
 */
@RestController
@RequestMapping("/user")
public class UserController {
    
    
    @PostMapping("/add")
    public boolean addUser(User user){
    
    
        return false;
    }
    @GetMapping("/find/{id}")
    public User findById(@PathVariable("id") int id) {
    
    
        return new User();
    }
    @PutMapping("/update")
    public boolean update(@RequestBody User user) {
    
    
        return true;
    }
    @DeleteMapping("/delete/{id}")
    public boolean delete(@PathVariable("id") int id) {
    
    
        return true;
    }
}

Código-fonte SwaggerConfig

package com.example.demo.config;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

/**
 * @Author 秋名山码神
 * @Date 2023/1/9
 * @Description
 */
@Configuration
@EnableSwagger2
public class SwaggerConfig {
    
    
    @Bean
//    配置Swagger的Docket的bean实例
    public Docket api(){
    
    
        return new Docket(DocumentationType.SWAGGER_2)
                .select()
//        RequestHandlerSelectors配置扫描接口的方式
                .apis(RequestHandlerSelectors.any())
//                path过滤什么路径
                .paths(PathSelectors.any())
                .build();
    }

@Configuration serve para informar ao Spring Boot que esta classe de configuração precisa ser carregada; @EnableSwagger2 serve para habilitar o Swagger2.

verificar

Inicie o projeto e visite http://localhost:8080/swagger-ui.html no navegador
insira a descrição da imagem aqui
para ver se o projeto começou a ser executado. Vamos explicar a configuração avançada no Swagger** (os comentários do código também estão muito bem escritos .claro)**

configuração avançada

Comentários sobre a documentação

Ao adicionar a anotação @Api à classe do controlador, você pode adicionar informações de descrição e rótulo ao controlador

@Api(tags = "用户相关接口",description = "提供用户相关的Rest API")
public class UserController {

Expanda a descrição da interface adicionando a anotação @ApiOperation no método de interface

@ApiOperation("添加用户操作")
    @PostMapping("/add")
    public boolean addUser(User user){
    
    
        return false;
    }

Descreva os objetos envolvidos em nossa API adicionando anotações @ApiModel e @ApiModelProperty na classe de entidade

@ApiModel("用户实体类")
public class User {
    
    
    @ApiModelProperty("用户名")
    private String username;
    @ApiModelProperty("密码")
    private String password;

Configuração de informações do documento, o Swagger também suporta a configuração de alguns números de versão do documento, caixas de correio de contato, sites, direitos autorais, contratos de código aberto, etc., mas diferente dos itens acima, essas informações não podem ser configuradas por meio de anotações, mas sim pela criação de um objeto ApiInfo, e usando o método appInfo() para definir, podemos adicionar o seguinte conteúdo na classe SwaggerConfig.java:

 @Bean
//    配置Swagger的Docket的bean实例
    public Docket api(){
    
    
        return new Docket(DocumentationType.SWAGGER_2)
                .select()
//        RequestHandlerSelectors配置扫描接口的方式
                .apis(RequestHandlerSelectors.any())
//                path过滤什么路径
                .paths(PathSelectors.any())
                .build();
    }
    private ApiInfo apiInfo() {
    
    
        return new ApiInfo(
                "Spring Boot 项目集成 Swagger 实例文档",
                "欢迎",
                "API V1.0",
                "Terms of service",
                new Contact("名字想好没", "csdn",              "163.com"),
                "Apache", "http://www.apache.org/", Collections.emptyList());
    }

filtragem de interface

Nota: Se você deseja bloquear um método de interface no documento, você só precisa adicionar @ApiIgnore ao método de interface

Adicione triagem no Docket. Docket fornece dois métodos, apis() e paths(), para nos ajudar a filtrar interfaces em diferentes níveis: apis
(): Dessa forma, podemos deixar o Swagger verificar apenas determinados pacotes, especificando o nome do pacote.
paths(): Este método pode ser filtrado filtrando a URL da API.

resposta personalizada

O método globalResponseMessage() do Docket substitui globalmente a mensagem de resposta do método HTTP, mas primeiro devemos dizer ao Swagger para não usar a mensagem de resposta HTTP padrão por meio do método useDefaultResponseMessage() do Docket, assumindo que precisamos cobrir todas as mensagens de resposta de erro dos métodos GET 500 e 403 . Precisamos apenas adicionar o seguinte conteúdo no Docket Bean da classe SwaggerConfig.java:

.useDefaultResponseMessages(false)
.globalResponseMessage(RequestMethod.GET, newArrayList(
new ResponseMessageBuilder()
              .code(500)
              .message("服务器发生异常")
              .responseModel(new ModelRef("Error"))
              .build(),
       new ResponseMessageBuilder()
              .code(403)
              .message("资源不可用")
              .build()
));

Uso do SwaggerUI

chamada de interface

insira a descrição da imagem aqui

Problemas encontrados:

O projeto de inicialização relata uma exceção de ponteiro nulo
insira a descrição da imagem aqui
Adicione este código:spring.mvc.pathmatch.matching-strategy=ANT_PATH_MATCHER

Explicação detalhada do uso do Swagger no SpringBoot