springcloud: explicação detalhada do gerador automático de interface do documento swagger Parte 1 (11)

0 Prefácio

No desenvolvimento de microsserviços, o desenvolvimento colaborativo de front e back end é essencial.Com o aumento do número de serviços e interfaces, a documentação de interfaces manuscritas tornou-se uma tarefa árdua, e muitos programadores também são muito resistentes a isso. Ao mesmo tempo, também precisamos de um local para gerenciar essas interfaces de maneira unificada.

Um grupo de programadores preguiçosos se perguntou se poderia haver uma ferramenta para gerar automaticamente este documento de interface, então outro grupo de programadores preguiçosos desenvolveu a ferramenta de geração automática de documentos de interface swagger

1. Introdução à arrogância

Swagger é essencialmente um serviço da Web para gerar, descrever e chamar interfaces no estilo REST. Além da documentação da interface, o swagger também suporta testes online. Insira os valores dos parâmetros diretamente na interface para testar

Agora na produção real, o knife4j que integra o swagger é usado para gerenciar documentos de interface, mas para a coerência dos pontos de conhecimento, vamos aprender o swagger primeiro, e o knife4j será explicado mais tarde.

2. Usando arrogância

2.1 Introduzindo o swagger em um único serviço

1. Adicione dependências de swagger ao serviço

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

2. Crie o arquivo de configuração do swagger SwaggerConfig

import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
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;

/**
 * @author whx
 * @date 2022/4/16
 */
@EnableSwagger2
@Configuration
public class SwaggerConfig {

    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                // api过滤器，设置哪些接口会加载创建接口文档
//                .apis(RequestHandlerSelectors.basePackage("com.xx.xx"))
                .apis(RequestHandlerSelectors.withClassAnnotation(Api.class))
                .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("商品服务接口文档")
                .description("商品服务接口文档说明：xxx")
                .contact(new Contact("55555", "", "[email protected]"))
                .version("1.0")
                .build();
    }

}

3. Adicione uma descrição
à classe de entidade Use anotações em classes de entidade Use anotações @ApiModel
em campos@ApiModelProperty

@Data
@ApiModel(value = "Product对象", description = "商品对象")
public class Product {

    @ApiModelProperty(value = "主键")
    private Long id;

    @ApiModelProperty(value = "商品名称")
    private String name;

    @ApiModelProperty(value = "商品编号")
    private String no;

    @ApiModelProperty(value = "商品价格")
    private Double price;

    @ApiModelProperty(value = "创建时间")
    private Date createTime;

}

4. Adicione uma descrição
ao controlador Adicione anotações a classes e @Apimétodos para adicionar anotações@ApiOperation

@RestController
@AllArgsConstructor
@Api(value = "商品Controller", tags = "商品接口")
public class ProductController {
    private final IProductService productService;

    @ApiOperation(value = "列表", notes = "无参数")
    @GetMapping("list")
    public List<Product> list(){
        return productService.list();
    }

    @ApiOperation(value = "保存", notes = "无参数")
    @PostMapping("save")
    public String save(){
        Product product = new Product();
        product.setId(555L);
        product.setName("商品xxx");
        product.setPrice(300.0);
        product.setNo("SP001");
        product.setCreateTime(new Date());
        int i = 1/0;
        return productService.save(product) ? "保存成功" : "保存失败";
    }
}

5. Reinicie o serviço e visite localhost:9091/swagger-ui.html. Aqui 9091 é o número da porta do serviço

Clique no controlador correspondente para ver a interface na camada de controle e clique na interface específica para ver a documentação detalhada da interface.

3. Anotações comuns

@Api：说明类的作用。作用位置Controller
    tags="说明该类的作用，标签"
    value="接口说明"

@ApiOperation：说明接口/方法的作用。作用位置：Controller方法
    value="接口名"
    notes="接口备注"
    
@ApiModel：说明实体类。作用位置：实体类
	 value="实体类名称"
	 description="实体类描述"
    @ApiModelProperty：实体类字段说明。作用位置：实体类字段
     	value=“字段的中文说明”
		name=“字段名”
		notes=“字段备注”
		required=“是否必填”
		hidden=“是否隐藏，默认false，为true时在swagger中不显示”
		dataType=“数据类型，可以设置为String,Integer等”
		allowableValues=“允许值”
	    
@ApiImplicitParams：用在Controller方法上，表示一组参数说明
    @ApiImplicitParam：用在@ApiImplicitParams注解中，说明这个参数的各种信息
        name=“参数名”
        value=“参数的中文说明”
        required=“参数是否比天”
        paramType=“参数位置，比如如果参数来自header，那么其值为header”
            · header: 请求头参数 @RequestHeader
            · query: 普通请求参数 @RequestParam
            · path：路径请求参数 @PathVariable
        dataType：参数类型，默认String，其它值dataType="Integer"       
        defaultValue：参数的默认值

@ApiResponses：用在Controller方法上，表示一组响应
    @ApiResponse：用在@ApiResponses中，一般用于表达一个错误的响应信息
        code=“状态码，例如400”
        message=“信息，例如‘请求参数没填好’”
        response=”抛出异常的类“

Portanto, neste ponto, nossa configuração de swagger para um único serviço está concluída. Não é simples.

Porém, já pensou em uma dúvida, se eu tiver vários outros serviços agora, então precisarei implantar os passos acima em cada serviço

Então, quando queremos acessar os documentos de interface de diferentes serviços, temos que trocar de porta, o que é muito problemático. Existe alguma maneira de resumir os arquivos de porta desses serviços em um serviço? Só precisamos acessar uma porta para ver todos os serviços Documentação da interface.

Ao mesmo tempo, você ainda se lembra do conceito sobre o qual falamos no Capítulo 8 de que todos os arquivos de configuração do nacosp são centralizados em uma classe de interface para configuração? Precisamos reduzir o trabalho repetitivo, então precisamos configurar o arquivo de configuração do swagger acima apenas uma vez?

Então, na próxima edição, começamos a configurar o verdadeiro springcloud + swagger

Siga a conta oficial Elasticsearch home para saber mais sobre novos conteúdos

Blogue de referência

https://zhuanlan.zhihu.com/p/161947638