swagger学习

swagger 支持基于 API 自动生成接口文档，接口文档始终与 API 保持同步，

一、引入依赖：

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

二、启动类

添加注解@EnableSwagger2；添加此注解后表示对当前项目中全部控制器进行扫描

@EnableSwagger2
@SpringBootApplication(scanBasePackages = {"", ""})
public class TestApplication {
    public static void main(String[] args) {
        SpringApplication.run(TestApplication.class, args);
        System.out.println("  ======= 启动成功 =======  ");
    }
}

三、添加swagger配置

@Configuration
public class SwaggerConfig {

	@Bean
	public Docket getDocket() {
		return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(swaggerApiInfo()) // 增加API相关信息
				.groupName("测试系统") //如果配置多个文档的时候，需要配置groupName来分组
                .select() //select()函数返回一个ApiSelectorBuilder实例,用来控制接口被swagger做成文档
			    .apis(RequestHandlerSelectors.basePackage("com.controller")) //指定扫描哪个包下的接口
                .host("") //指定访问swaggerUI界面的地址
				.build();
	}


	private ApiInfo swaggerApiInfo() {
		return new ApiInfoBuilder()
				// 联系人信息 name url email
				.contact(new Contact("", "", ""))
				// 文档标题
				.title("Swagger 的标题")
				// 文档描述
				.description("Swagger 的描述")
				// 文档版本
				.version("3.0.0")
                .build();
	}

}

四、Controller层

@Api

该注解将一个Controller（Class）标注为一个swagger资源（API）。在默认情况下，Swagger-Core只会扫描解析具有@Api注解的类；该注解的属性有：

tags ：分组的标签；具有相同标签的API将会被归并在一组内展示

value：是类的说明，可以使用tags替代        

@ApiOperation

在指定的（路由）路径上，表示一个http请求的操作。具有相同路径的不同操作会被归组为同一个操作对象。

notes：接口的描述

value：可以当作是接口的简称

tags：可以重新分组

例如;

@RestController
@RequestMapping("/test")
@Api(tags = "测试接口")
public class TestController {
    @ApiOperation("查询接口")
    @GetMapping("/query")
    public void TestList(TestListDto testListDto) {

    }
}

五、输入、输出:

@ApiModel

修饰对象类，表示对对象类进行说明，用于参数用实体类接收的场景

value：表示对象名，可省略

description：描述，可省略

@ApiModelProperty

用来描述一个model的属性；表示这个属性是一个Swagger模型的属性。主要的属性值有：

value 属性简短描述；默认属性

name 重写属性的名字

example 属性的示例值

required 指定属性是否为必须值

例如：

@Data
@ApiModel
public class ResponseVo {

    @ApiModelProperty(name = "名字")
    private String name;
}

六、访问UI页面

进入http://ip:port/swagger-ui.html

在页面中可以通过可视化的进行操作项目中所有接口

七、注意

如果使用swagger访问接口，传入参数为空时

可以试试

@RestController
@RequestMapping("/test")
@Api(tags = "测试接口")
public class TestController {
    //显示的指定参数名
    @ApiOperation("查询接口")
    @GetMapping("/query")
    public void TestList(@RequestParam("paramName") String username) {

    }

    //或者换成post请求
    @ApiOperation("查询接口")
    @PostMapping("/query")
    public void TestList(@RequestBody TestListDto testListDto) {

    }
}

@RequestParam(required = false)

设置为非必传。因为required值默认是true，默认必传

@RequestParam("workID")或者@RequestParam(value = "workID")

可以指定参数名