springboot 结合 swagger2

Myth丶恋晨 2021-09-18 04:12 418阅读 0赞

### spring boot 结合 swagger2 ###

#### 1. swagger 简介 ####

Swagger 是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。

#### 2. 功能 ####

1.  接口文档在线生成
2.  功能测试

感悟：现在的项目大部分都是前后端分离的，这样后端在写好后台接口后，在进行接口测试时，以往都是使用 postman 等工具来进行，这样很麻烦。swagger 很好的解决了这个问题。

#### 3. 如何使用 ####

1.  Maven依赖

如果只引入 swagger 依赖，可能会报错，找不到某个类，所以还需要导入 google 的guava 包

<dependency>
    	<groupId>io.springfox</groupId>
    	<artifactId>springfox-swagger2</artifactId>
    	<version>2.6.1</version>
    </dependency>
    <dependency>
    	<groupId>io.springfox</groupId>
    	<artifactId>springfox-swagger-ui</artifactId>
    	<version>2.6.1</version>
    </dependency>
    <dependency>
    	<groupId>com.google.guava</groupId>
    	<artifactId>guava</artifactId>
    	<version>19.0</version>
    </dependency>

1.  创建 SwaggerConfig 配置类

import org.springframework.context.annotation.Bean;
    import org.springframework.context.annotation.Configuration;
    import org.springframework.web.servlet.config.annotation.ResourceHandlerRegistry;
    import org.springframework.web.servlet.config.annotation.WebMvcConfigurerAdapter;
    
    import springfox.documentation.builders.ApiInfoBuilder;
    import springfox.documentation.builders.PathSelectors;
    import springfox.documentation.builders.RequestHandlerSelectors;
    import springfox.documentation.service.ApiInfo;
    import springfox.documentation.spi.DocumentationType;
    import springfox.documentation.spring.web.plugins.Docket;
    import springfox.documentation.swagger2.annotations.EnableSwagger2;
    
    @Configuration
    @EnableSwagger2
    public class Swagger2Configure extends WebMvcConfigurerAdapter {
    
        @Override
        public void addResourceHandlers(ResourceHandlerRegistry registry) {
            registry.addResourceHandler("/js/**").addResourceLocations("classpath:/js/");
            registry.addResourceHandler("swagger-ui.html").addResourceLocations("classpath:/META-INF/resources/");
            registry.addResourceHandler("/webjars/**").addResourceLocations("classpath:/META-INF/resources/webjars/");
        }
    
        @Bean
        public Docket createRestApi() {
            return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo()).select()
                    .apis(RequestHandlerSelectors.basePackage("com.xxx.controller"))
                    .paths(PathSelectors.any()).build();
        }
    
        private ApiInfo apiInfo() {
            return new ApiInfoBuilder().title("xxx RESTful APIs").description("xxx api 接口文档").version("1.0").build();
        }
    }

1.  编写 controller

@Api(value= "Test",description="测试 Test")
    @RestController
    @RequestMapping("/api")
    public class Test {
    	// 如果没有标注请求方式，页面默认显示所有的请求方法
    	@ApiOperation(value = "测试 api", notes = "测试 api 接口")
    	@RequestMapping(value = "/test",method = ResquestMethod.GET)
    	@ApiImplicitParam(name = "username", value = "测试", required = true, paramType = "query")
    	public void test(@RequestParam String username) {
    		System.out.println("用户名" + username);
    	}
    }

1.  参数说明

<table> 
 <thead> 
  <tr> 
   <th>注解</th> 
   <th>注解说明</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td>@Api</td> 
   <td>用在类上，说明该类的作用</td> 
  </tr> 
  <tr> 
   <td>@ApiOperation</td> 
   <td>注解给 Api 方法说明</td> 
  </tr> 
  <tr> 
   <td>@ApiImplicitParams</td> 
   <td>用在方法上，包含一组参数说明</td> 
  </tr> 
  <tr> 
   <td>@ApiImplicitParam</td> 
   <td>用来注解来给方法入参增加说明</td> 
  </tr> 
  <tr> 
   <td>@ApiResponses</td> 
   <td>用于表示一组响应</td> 
  </tr> 
  <tr> 
   <td>@ApiResponse</td> 
   <td>用在@ApiResponses中，一般用于表达一个错误的响应信息</td> 
  </tr> 
  <tr> 
   <td>@ApiModel</td> 
   <td>描述一个Model的信息（一般用在请求参数无法使用@ApiImplicitParam注解进行描述的时候）</td> 
  </tr> 
  <tr> 
   <td>@ApiModelProperty</td> 
   <td>描述一个model的属性</td> 
  </tr> 
 </tbody> 
</table>

@ApiImplicitParam

在使用 swagger 时，页面中输入参数，后台总是获取不到，发现是 @ApiImplicitParam 注解用的方式不对

记录 @ApiImplicitParam 参数说明：

<table> 
 <thead> 
  <tr> 
   <th>参数名称</th> 
   <th>作用</th> 
   <th>备注</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td>paramType</td> 
   <td>指定参数放在哪个地方</td> 
   <td>header：请求参数放置于Request Header，使用@RequestHeader获取;query：请求参数放置于请求地址，使用@RequestParam获取;path：（用于restful接口）–&gt;请求参数的获取：@PathVariable;body:(不常用);form（不常用）</td> 
  </tr> 
  <tr> 
   <td>name</td> 
   <td>参数名</td> 
   <td></td> 
  </tr> 
  <tr> 
   <td>dataType</td> 
   <td>参数类型</td> 
   <td></td> 
  </tr> 
  <tr> 
   <td>required</td> 
   <td>参数是否必须传</td> 
   <td></td> 
  </tr> 
  <tr> 
   <td>value</td> 
   <td>说明参数的意思</td> 
   <td></td> 
  </tr> 
  <tr> 
   <td>defaultValue</td> 
   <td>参数的默认值</td> 
   <td></td> 
  </tr> 
 </tbody> 
</table>