SpringBoot整合Swagger
Swagger-UI
Swagger-UI是HTML, Javascript, CSS的一个集合,可以动态地根据注解生成在线API文档。
1、常用注解
- @Api:用于修饰Controller类,生成Controller相关文档信息
- @ApiModel()用于类 ;对类进行说明
value–表示对象名
description–描述 - @ApiModelProperty:用于修饰实体类的属性,当实体类是请求参数或返回结果时,直接生成相关文档信息
- @ApiOperation() 用于方法;表示一个http请求的操作 ;通常修饰Controller类中的方法,生成接口方法相关文档信息
value用于方法描述
notes用于提示内容
tags可以重新分组(视情况而用) - @ApiParam() 用于方法,参数,字段说明;表示对参数的添加元数据(说明或是否必填等);
name–参数名
value–参数说明
required–是否必填 - @ApiImplicitParam() 用于方法 ;表示单独的请求参数
- @ApiImplicitParams() 用于方法,包含多个 @ApiImplicitParam
name–参数ming
value–参数说明
dataType–数据类型
paramType–参数类型
example–举例说明
2、整合Swagger-UI
添加项目依赖:在pom.xml中新增Swagger-UI相关依赖
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.7.0</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.7.0</version>
</dependency>
<dependency>
<groupId>io.swagger</groupId>
<artifactId>swagger-annotations</artifactId>
<version>1.6.0</version>
</dependency>
3、添加Swagger-UI的配置
添加Swagger-UI的Java配置文件,Swagger对生成API文档的范围有三种不同的选择:
- 生成指定包下面的类的API文档
- 生成有指定注解的类的API文档
- 生成有指定注解的方法的API文档
/**
* Swagger2API文档的配置
*/
@Configuration
@EnableSwagger2
public class Swagger2Config {
@Bean
public Docket createRestApi(){
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
//为当前包下controller生成API文档
.apis(RequestHandlerSelectors.basePackage("com.woniuxy.controller"))
//为有@Api注解的Controller生成API文档
// .apis(RequestHandlerSelectors.withClassAnnotation(Api.class))
//为有@ApiOperation注解的方法生成API文档
// .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
.paths(PathSelectors.any()) //对所有路径进行监控
.build();
}
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("SwaggerUI演示")
.description("demo")
.contact("admin")
.version("1.0")
.build();
}
}
示例
@ApiOperation("查询测试")
@GetMapping("select")
@ApiImplicitParam(name="name",value="用户名",dataType="String", paramType = "query") @ApiImplicitParams({ @ApiImplicitParam(name="name",value="用户名",dataType="string", paramType = "query",example="xingguo"), @ApiImplicitParam(name="id",value="用户id",dataType="long", paramType = "query")})
public void select(String name,long id){ }
访问Swagger-UI接口文档地址
接口地址:http://localhost:8080/swagger-ui.html
在Spring Boot中使用swagger-bootstrap-ui
swagger-bootstrap-ui
是基于swagger接口api实现的一套UI,因swagger原生ui是上下结构的,在浏览接口时不是很清晰,所以,swagger-bootstrap-ui
是基于左右菜单风格的方式,方便浏览。
GitHub: https://github.com/xiaoymin/Swagger-Bootstrap-UI
<!--引入ui包-->
<dependency>
<groupId>com.github.xiaoymin</groupId>
<artifactId>swagger-bootstrap-ui</artifactId>
<version>1.9.6</version>
</dependency>
接口访问
在浏览器输入:http://${host}:${port}/doc.html
swagger-bootstrap-ui 指南
https://www.bookstack.cn/read/swagger-bootstrap-ui/quickstart.md