swagger 依赖及应用

左手的ㄟ右手 2023-10-07 20:47 11阅读 0赞

**目录**

Swagger依赖

Swagger常用注解

Swagger代码

--------------------

## Swagger依赖 ##

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

## Swagger常用注解 ##

在Java类中添加Swagger的注解即可生成Swagger接口文档，常用Swagger注解如下：

@Api：修饰整个类，描述Controller的作用

@ApiOperation：描述一个类的一个方法，或者说一个接口

@ApiParam：单个参数的描述信息

@ApiModel：用对象来接收参数

@ApiModelProperty：用对象接收参数时，描述对象的一个字段

@ApiResponse：HTTP响应其中1个描述

@ApiResponses：HTTP响应整体描述

@ApiIgnore：使用该注解忽略这个API

@ApiError ：发生错误返回的信息

@ApiImplicitParam：一个请求参数

@ApiImplicitParams：多个请求参数的描述信息

@ApiImplicitParam属性：

<table> 
 <thead> 
  <tr> 
   <th>属性</th> 
   <th>取值</th> 
   <th>作用</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td>paramType</td> 
   <td></td> 
   <td>查询参数类型</td> 
  </tr> 
  <tr> 
   <td></td> 
   <td>path</td> 
   <td>以地址的形式提交数据</td> 
  </tr> 
  <tr> 
   <td></td> 
   <td>query</td> 
   <td>直接跟参数完成自动映射赋值</td> 
  </tr> 
  <tr> 
   <td></td> 
   <td>body</td> 
   <td>以流的形式提交 仅支持POST</td> 
  </tr> 
  <tr> 
   <td></td> 
   <td>header</td> 
   <td>参数在request headers 里边提交</td> 
  </tr> 
  <tr> 
   <td></td> 
   <td>form</td> 
   <td>以form表单的形式提交 仅支持POST</td> 
  </tr> 
  <tr> 
   <td>dataType</td> 
   <td></td> 
   <td>参数的数据类型 只作为标志说明，并没有实际验证</td> 
  </tr> 
  <tr> 
   <td></td> 
   <td>Long</td> 
   <td></td> 
  </tr> 
  <tr> 
   <td></td> 
   <td>String</td> 
   <td></td> 
  </tr> 
  <tr> 
   <td>name</td> 
   <td></td> 
   <td>接收参数名</td> 
  </tr> 
  <tr> 
   <td>value</td> 
   <td></td> 
   <td>接收参数的意义描述</td> 
  </tr> 
  <tr> 
   <td>required</td> 
   <td></td> 
   <td>参数是否必填</td> 
  </tr> 
  <tr> 
   <td></td> 
   <td>true</td> 
   <td>必填</td> 
  </tr> 
  <tr> 
   <td></td> 
   <td>false</td> 
   <td>非必填</td> 
  </tr> 
  <tr> 
   <td>defaultValue</td> 
   <td></td> 
   <td>默认值</td> 
  </tr> 
 </tbody> 
</table>

## Swagger代码 ##

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;
    
    @Configuration
    @EnableSwagger2
    public class SwaggerConfiguration {
    
       @Bean
       public Docket buildDocket() {
          return new Docket(DocumentationType.SWAGGER_2)
                  .apiInfo(buildApiInfo())
                  .select()
                  // 要扫描的API(Controller)基础包
                  .apis(RequestHandlerSelectors.basePackage("com.***"))
                  .paths(PathSelectors.any())
                  .build();
       }
    
       private ApiInfo buildApiInfo() {
          Contact contact = new Contact("文档标题","","");
          return new ApiInfoBuilder()
                  .title("***项目API文档")
                  .description("***项目后台api")
                  .contact(contact)
                  .version("1.0.0").build();
       }
    }

> 注意：
> 
> 在模块common模块中的resources目录中新增以下目录和文件
> 
> 文件：resources/META-INF/Spring.factories

org.springframework.boot.autoconfigure.EnableAutoConfiguration=\
      com.***.common.swagger.SwaggerConfiguration
    
    如果是多个 用 ,\换行 例如
    
    org.springframework.boot.autoconfigure.EnableAutoConfiguration=\
      com.***.common.exception.ExceptionCatch,\
      com.***.common.swagger.SwaggerConfiguration