SpringBoot integra Swagger2
Ao fazer o pós-desenvolvimento de alguns projetos antigos, descobriremos que a maioria das empresas faz projetos com base nos documentos de desenvolvimento escritos pelo gerente de projeto, e os programadores em segundo plano desenvolvem a interface de acordo com os documentos da interface. will Alguns problemas foram encontrados, pois o código foi alterado após algumas pequenas alterações, mas o documento não foi atualizado imediatamente, o que fez com que o código não correspondesse ao código ao ler o documento posteriormente
Anteriormente, eram usados documentos de interface escritos por palavra.Na maioria dos casos, existem vários problemas:
- Atualização em tempo real de documentos e códigos de interface
- Problemas de especificação para documentação de interface
- Existem muitos documentos de interface, o que é inconveniente de gerenciar
Assim surgiu a ferramenta Swagger para geração automática de documentos API. Suas vantagens são:
- O Swagger pode gerar automaticamente documentos de API e funções de teste online
- Swagger pode ser rapidamente integrado e usado com SpringBoot
Swagger2 tutorial
1. Introduzir dependências no pom
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.2.2</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.2.2</version>
</dependency>
2. Escreva a classe de configuração do Swagger2
/**
* Swagger2 配置类
* 在与spring boot 集成时，放在与application.java 同级的目录下
* 通过@Configuration注解，让spring来加载该配置
* 再通过@EnableSwagger2注解来启动Swagger2
*/
@Configuration
@EnableSwagger2
public class Swagger2 {
/**
* 创建API应用
* appinfo()增加API相关信息
* 通过select()函数返回一个ApiSelectorBuilder实例，用来控制那些接口暴露给Swagger来展现
* 本例采用置顶扫描的包路径来定义指定要建立API的目录
*
* @return
*/
@Bean
public Docket createRestApi() {
Docket docket = new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
.apis(RequestHandlerSelectors.basePackage("com.Jason.chat"))
.paths(PathSelectors.any()).build();
return docket;
}
/**
* 创建改API的基本信息（这些基本信息会展示在文档页面中）
* 访问地址： http://项目实际地址/swagger-ui.html
* @return
*/
public ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("springboot利用swagger构建api文档")
.description("简单优雅的restfun风格，https://blog.csdn.net/weixin_43650254")
.termsOfServiceUrl("https://blog.csdn.net/weixin_43650254")
.contact("Jason")
.version("1.0")
.build();
}
}
3. Use anotações para realizar o Swagger para gerar documentos de API automaticamente
@Api: Usado em uma classe para descrever a função da classe.
@ApiOperation: anotações para adicionar descrições de métodos à API.
@ApiImplicitParams : Usado em métodos para conter um conjunto de descrições de parâmetros.
@ApiImplicitParam: Usado para anotar para adicionar descrições aos parâmetros de entrada do método.
@ApiResponses: Usado para representar um conjunto de respostas
@ApiResponse: Usado em @ApiResponses, geralmente usado para expressar uma mensagem de resposta errada
-
código: número, como 400
-
mensagem: informações, como "os parâmetros da solicitação não foram preenchidos"
-
resposta: a classe que lançou a exceção
@ApiModel: Descreve as informações de um Model (geralmente usado quando o parâmetro da requisição não pode ser descrito usando a anotação @ApiImplicitParam)
- @ApiModelProperty: descreve as propriedades de um modelo
Observação: a descrição do parâmetro de @ApiImplicitParam:
| parâmetro | ilustrar |
|---|---|
| paramType: especifique onde o parâmetro é colocado | cabeçalho: os parâmetros da solicitação são colocados no cabeçalho da solicitação, use @RequestHeader para obter a consulta: os parâmetros da solicitação são colocados no endereço da solicitação, use @RequestParam para obter o caminho: (para interface restful) –> obter os parâmetros da solicitação: @PathVariable corpo: (não é comum usado) forma (pouco usado) |
| nome: nome do parâmetro | |
| dataType: tipo de parâmetro | |
| obrigatório: Se o parâmetro deve ser passado | verdadeiro | falso |
| value: Explique o significado do parâmetro | |
| defaultValue: o valor padrão do parâmetro |