Adicione o Swagger ao projeto SpringBoot para gerar automaticamente a documentação da API + (swagger-bootstrap-ui) otimização da interface da documentação + como modificar o documento não pode ser encontrado

No desenvolvimento da separação de front-end e back-ends, o back-end precisa fornecer a documentação da interface da API para o front-end, o que é uma etapa muito importante. No entanto, a escrita e atualização de documentos de interface também leva muito tempo durante o processo de desenvolvimento, especialmente o conteúdo de alguns parâmetros, é fácil para o pessoal de front-end deixar de usar a interface devido à escrita incorreta. O Swagger nasceu para resolver esse problema. Durante o processo de desenvolvimento, documentos API são gerados automaticamente de acordo com os parâmetros configurados pelos desenvolvedores de back-end. Este artigo é sobre as funções básicas de uso deste plug-in no projeto Springboot.

Um, Swagger está preocupado com a solução

anotação	Introdução
@Api	@Api é usado em uma classe para ilustrar o papel da classe. Você pode marcar uma classe Controller como um recurso de documento Swagger
@ApiParam	Descrição dos parâmetros usados ​​para métodos no controlador
@@ ApiOperation	Usado no método no Controlador, explique o papel do método, a definição de cada interface
@ApiImplicitParam e @ApiImplicitParams	Usado no método, para explicar os parâmetros de solicitação individuais
@ApiModel	Usado para campos, indicando a descrição dos atributos do modelo
@ApiModelProperty	Indica a descrição da classe, que é usada para descrever a recepção do parâmetro na classe de entidade
@ApiResponse e @ApiResponses	@ApiResponse é usado no método para explicar algumas informações da resposta da interface; @ApiResponses monta vários @ApiResponse

Aqui está uma breve introdução. Para obter detalhes, consulte o uso específico no projeto springboot abaixo.

Em segundo lugar, o aplicativo real no projeto springboot
(1) citou a dependência

<!--Swagger依赖-->
	<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>

As duas dependências apresentadas aqui, a primeira é a dependência swagger. Depois de introduzir essa dependência, você pode visualizar o documento json retornado, que é muito pesado e complicado, e a legibilidade é extremamente pobre. Neste momento, uma IU de exibição é necessária Após a introdução, é uma dependência da bravata exibir a IU.
(2) Configurar arrogância

@Configuration
@EnableSwagger2
@ComponentScan(basePackages = {
    
     "com.example.api.controller" })
public class SwaggerConfig {
    
    
    @Bean
    public Docket buildDocket(){
    
    
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(buildApiInf())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.example.api.controller"))
                .paths(PathSelectors.any())
                .build();
    }
    private ApiInfo buildApiInf(){
    
    
        return new ApiInfoBuilder()
                //页面标题
                .title("秒杀商城API文档")
                //描述
                .description("简单优雅的restful风格")
                //创建人信息
                .contact(new Contact("Curry-Kun","127.0.0.1:8080/","[email protected]"))
                .termsOfServiceUrl("")
                //版本号
                .version("1.0")
                .build();
    }
}

(Três) classe de interface de configuração e classe de entidade
1. camada do controlador

@RestController
@RequestMapping("/miaosha")
@Api(tags = "秒杀功能模块API")
public class MiaoshaAPIController {
    
    

    @Autowired
    ProductService productService;

    @ApiImplicitParams({
    
    
            @ApiImplicitParam(name = "pageNo",value = "页码数",required = true,dataType = "int",paramType = "query"),
            @ApiImplicitParam(name = "pageSize",value = "展示条数",required = true,dataType = "int",paramType = "query")
    })

    /**
     * 商品列表页api
     * @request
     * pageNo
     * pageSize
     * @response
     * success
     * fail
     *
     * */
    @ApiOperation(value = "查询系统秒杀商品列表",notes = "采取分页的形式展示，需要pageNo页码数和pageSize每页展示条数")
    @PostMapping(value = "product_list_api")
    public ResponseResult product_list_api(@RequestParam(value = "pageNo",defaultValue = "1")int pageNo,
                                           @RequestParam(value = "pageSize",defaultValue = "6")int pageSize,
                                           User user){
    
    
        if(user == null){
    
    
            return ResponseResult.error(ResponseCode.NO_LOGIN);
        }
        PageInfo<ProductVo> page = productService.listProcuctVo(pageNo,pageSize);
        return ResponseResult.success(page);
    }

Isso envolve o uso de @Api, @ApiImplicitParams, @ApiImplicitParam e @ApiOperation. No código acima, você pode ver suas respectivas funções com mais detalhes.
Pensei que os resultados retornados estão todos encapsulados em ResponseResult, então ele também precisa ser anotado

@Data
@ApiModel
public class ResponseResult<T> {
    
    
    @ApiModelProperty(value = "返回状态码")
    private int code;
    @ApiModelProperty(value = "返回信息")
    private String msg;
    @ApiModelProperty(value = "返回数据")
    private T data;
    /**
     * 不同的data数据类型对应不同的ResponseResult的类型
     * */

    /**
     *return code message data 方法构造器
     * */
    public ResponseResult(ResponseCode rc,T data) {
    
    
        this.data = data;
        this.msg = rc.msg;
        this.code = rc.id;
    }
    /**
     * return code message
     * */
    public ResponseResult(ResponseCode rc) {
    
    
        this.msg = rc.msg;
        this.code = rc.id;
    }
    /**
     * success
     * */
    public static <T> ResponseResult<T> success(T data){
    
    
        return new ResponseResult<T>(ResponseCode.SERVER_SUCCESS,data);
    }
    /**
     * error
     * */
    public static  <T> ResponseResult<T> error(ResponseCode rc){
    
    
        return new ResponseResult<T>(rc);
    }
}

Isso envolve o uso de anotações @ApiModel e @ApiModelProperty.
Inicie o projeto e visite http: // {ip}: {port} /swagger-ui.html#/

(4) Otimize a IU A
IU acima ainda não é muito conveniente de usar. Você também pode torná-la mais amigável página. swagger-bootstrap-ui
1. Introduzir dependências

<dependency>
		<groupId>com.github.xiaoymin</groupId>
		<artifactId>swagger-bootstrap-ui</artifactId>
		<version>1.6</version>
	</dependency>

Neste momento, você precisa visitar http: // {ip}: {port} /doc.html

e suportar a depuração online. Contanto que as anotações que você escreve sejam detalhadas o suficiente, os novatos podem entendê-las.

3. O que devo fazer se não conseguir encontrar a página de documentação da API gerada?
1. Erro de página não pode ser acessado: Nenhum mapeamento para GET /swagger-ui.html
Essa situação ocorre porque o sistema passa o swagger-ui.html solicitado como um parâmetro, o que definitivamente causará um erro. Neste momento, você precisa modificar o WebMvcConfigurer, interceptar swagger-ui.html e configurar o local do arquivo.

@Configuration
public class WebConfig implements WebMvcConfigurer{
    
    

    @Override
    public void addResourceHandlers(ResourceHandlerRegistry registry) {
    
    
        registry.addResourceHandler("doc.html")//swagger-ui.html
                .addResourceLocations("classpath:/META-INF/resources/");
        registry.addResourceHandler("/webjars/**")
                .addResourceLocations("classpath:/META-INF/resources/webjars/");

    }
}

2. Uma página em branco
aparece após a visita. Nesse caso, você deve confirmar se a dependência da IU usada pelo swagger é importada normalmente. É provável que a dependência não seja importada, fazendo com que o arquivo swagger-ui.html não seja encontrado . Vá para dom.xml para rastreá-lo. Ou ao visualizar as dependências do sistema, se você confirmar que não há dependências de IU necessárias, você pode fazer o downgrade das dependências para uso.