SpringBoot集成Swagger
1、创建一个项目导入依赖
<!-- springfox-swagger-ui -->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.9.2</version>
</dependency>
<!-- springfox-swagger2 -->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.9.2</version>
</dependency>
=======================第二种=====================
<!-- swagger-bootstrap-ui -->
<dependency>
<groupId>com.github.xiaoymin</groupId>
<artifactId>swagger-bootstrap-ui</artifactId>
<version>1.9.6</version>
</dependency>
<!-- 使用1.5.22-->
<dependency>
<groupId>io.swagger</groupId>
<artifactId>swagger-models</artifactId>
<version>1.5.22</version>
</dependency>
<!-- springfox-swagger2 -->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.9.2</version>
<exclusions>
<exclusion>
<artifactId>swagger-models</artifactId>
<groupId>io.swagger</groupId>
</exclusion>
</exclusions>
</dependency>
<dependency>
<groupId>junit</groupId>
<artifactId>junit</artifactId>
<scope>test</scope>
</dependency>
启动swagger
第一种可以访问http://localhost:8080/swagger-ui.html进入开启swagger
第二种访问http://localhost:8080/doc.html
下面是第二种访问的结果
[外链图片转存失败,源站可能有防盗链机制,建议将图片保存下来直接上传(img-D2CO9DNd-1685604638549)(C:\Users\24128\AppData\Roaming\Typora\typora-user-images\image-20230527181510381.png)]
注意:在swagger3.0的版本进不去这个页面的
@Configuration
@EnableSwagger2
public class SwaggerConfig {
}
配置Swagger的信息
配置bean => Docket
@Bean
public Docket docket() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
// RequestHandlerSelectors : 配置要扫描的方式
/*方式如下:
* basePackage : 扫描指定的包下
* any : 扫描所有的 none : 不扫描
* withMethodAnnotation : 扫描方法上的注解(传入注解class)
* withClassAnnotation : 扫描类上的注解(传入注解class)
*/
.apis(RequestHandlerSelectors.basePackage("cn.wolfcode.swagger.controller") )
//过滤路径 只有符合下面的才会出现在swagger中
.paths(PathSelectors.ant("/test/**"))
.build();
}
private ApiInfo apiInfo() {
//作者信息
Contact contact = new Contact("小狼", "http://wolfcode.cn", "xiaolang123@qq.com");
return new ApiInfo(
"小狼Swagger文档",
"接口开发文档",
"v1.0",
"http://wolfcode.cn",
contact,
"Apache 2.0",
"http://www.apache.org/licenses/LICENSE-2.0",
new ArrayList());
}
配置是否启动swagger:**enable(false)**表示禁用
判断环境是开发环境dev就启用swagger,是生产环境就禁用swagger
[外链图片转存失败,源站可能有防盗链机制,建议将图片保存下来直接上传(img-2BCNwLa6-1685604638550)(C:\Users\24128\AppData\Roaming\Typora\typora-user-images\image-20230526155131103.png)]
配置api分组
.groupName("部门")
配置多个分组,只需要配置多个Docket的bean就行了
常用注解
注解 | 描述 |
---|---|
@Api | 将类标记为 Swagger 资源。 |
@ApiImplicitParam | 表示 API 操作中的单个参数。 |
@ApiImplicitParams | 允许多个 ApiImplicitParam 对象列表的包装器。 |
@ApiModel | 提供有关 Swagger 模型的其他信息。 |
@ApiModelProperty | 添加和操作模型属性的数据。 |
@ApiOperation | 描述针对特定路径的操作或通常是 HTTP 方法。 |
@ApiParam | 为操作参数添加额外的元数据。 |
@ApiResponse | 描述操作的可能响应。 |
@ApiResponses | 允许多个 ApiResponse 对象列表的包装器。 |
@Authorization | 声明要在资源或操作上使用的授权方案。 |
@AuthorizationScope | 描述 OAuth2 授权范围。 |
@Api
@Api注解用在类上,说明该类的作用。可以标记一个Controller类做为swagger文档资源。
案例演示
@RestController
@Api(value = "书本管理",tags = {"书本管理"}) //tags可以代替value属性
@RequestMapping("/book")
public class BookController {
...
}
@ApiOperation
@ApiOperation注解用在方法上,说明方法的作用,每一个url资源的定义。
案例演示
@ApiOperation(value = "查询所有书本信息", notes = "查询返回所有书本信息集合",
produces = "application/json")
@GetMapping(value="/queryAll")
public JsonResponseBody<List<Book>> queryAll(){
try {
return bookService.queryAll();
} catch (Exception e) {
e.printStackTrace();
return new JsonResponseBody<>(500,e.getMessage());
}
}
@ApiImplicitParam
@ApilmplicitParam 注解用来描述一个参数,可以配置参数的中文含义,也可以给参数设置默认值,这样在接口测试的时候可以避免手动输入;
属性 | 说明 |
---|---|
paramType | 参数放在哪个地方 |
name | 参数名称 |
dataType | 参数类型 |
required | 是否必要 |
defaultValue | 参数的默认值 |
paramType的类型
类型 | 作用 |
---|---|
path | 以地址的形式提交数据,用于restful接口。请求参数采用@PathVariable获取 |
query | 直接跟参数完成自动映射赋值。请求参数可采用@RequestParam获取 |
body | 以流的形式提交,仅支持POST。请求参数采用@RequestBody获取 |
header | 参数在request headers里边提交。请求参数采用@RequestHeader获取 |
form | 以form表单的形式提交,仅支持POST。 |
案例演示
@ApiOperation(value="查询单个书本信息",notes = "查询单个书本信息")
@ApiImplicitParam(value="书本ID",name="bookid",required = true,dataType = "String",defaultValue = "8f46b5018a6811e9a9c528d24413c293" )
@GetMapping("/querySingleBook")
public Book querySingleBook(String bookid){
JsonResponseBody<Book> json = bookService.selectByPrimaryKey(bookid);
return json.getData();
}
@ApiImplicitParams
@ApilmplicitParams 如果有多个参数,则需要使用多个 @ApilmplicitParam 注解来描述, 多个 @ApilmplicitParam 注解需要放在一个 @ApilmplicitParams 注解中;
案例演示
@ApiOperation(value = "新增书本信息", notes = "新增书本信息"
,produces = "application/json",consumes = "application/json")
@ApiImplicitParams({
@ApiImplicitParam(name="bookname",value="书本名称",required = true,dataType = "String"),
@ApiImplicitParam(name="price",value="书本价格",required = true,dataType = "Double"),
@ApiImplicitParam(name="booktype",value="书本类型",required = true,dataType = "String")
})
@PostMapping("/addBook")
public JsonResponseBody<?> addBook(@RequestParam String bookname,
@RequestParam Double price,
@RequestParam String booktype){
return bookService.insert(Book.builder()
.bookid(UUID.randomUUID().toString().replace("-",""))
.bookname(bookname)
.booktype(booktype)
.price(price)
.build());
}
@ApiModel和@ApiModelProperty
-- 这两个注解主要是贴在domain实体类中的,当前端使用json传递数据的时候,后端的方法使用一个对象来接收时使用
@ApiModel注解描述一个Model的信息(这种一般用在post创建的时候,使用@RequestBody这样的场景,请求参数无法使用 @ApiImplicitParam注解进行描述的时候;
@ApiModelProperty注解描述一个model的属性。
案例演示
@ApiOperation(value="修改书本信息",notes = "修改书本信息")
@PostMapping("/editBook")
public JsonResponseBody<?> editBook(@RequestBody Book book){
return bookService.updateByPrimaryKey(book);
}
实体类
@Data
@Builder
@AllArgsConstructor
@NoArgsConstructor
@ApiModel(value="书本对象")
public class Book implements Serializable {
@ApiModelProperty(value="书本编号")
private String bookid;
@ApiModelProperty(value="书本名称")
private String bookname;
@ApiModelProperty(value="书本价格")
private Double price;
@ApiModelProperty(value="书本类型")
private String booktype;
private static final long serialVersionUID = 1L;
}
@ApiParam
作用在方法的参数上,用来描述接口的参数信息(一个参设置一个)
@ApiParam必须与@RequestParam、@PathVariable和@RequestHeader一起使用。
案例演示
@ApiOperation(value="新增书本信息1",notes="新增书本信息1")
@PostMapping("/addBooks")
public JsonResponseBody<?> addBooks(
@ApiParam(name="bookName",value="bookName",required = true) @RequestParam("bookName") String bookName,
@ApiParam(name="price",value="price",required = true) @RequestParam("price") float price,
@ApiParam(name="bookType",value="bookType",required = true) @RequestParam("bookType") String bookType){
System.out.println("bookName="+bookName+",price="+price+",bookType="+bookType);
return new JsonResponseBody<>();
}
生产环境下屏蔽Swagger2
@Profile
添加@Profile注解,指明在何种环境下可以使用Swagger2,一般情况下只有在开发(dev)和测试(test)环境下才可以使用Swagger2;而在生产(dev)环境下不能使用Swagger2。
@Configuration
//开启Swagger2
@EnableSwagger2
//配置生产环境下不可用 dev(开发)、test(测试)、prod(生产)
@Profile({"dev","test"})
public class Swagger2Configuration extends WebMvcConfigurationSupport {
...
@Override
protected void addResourceHandlers(ResourceHandlerRegistry registry) {
registry.addResourceHandler("doc.html")
.addResourceLocations("classpath:/META-INF/resources/");
registry.addResourceHandler("/webjars/**")
.addResourceLocations("classpath:/META-INF/resources/webjars/");
}
}
修改application.yml
修改application.yml文件,配置项目系统的运行环境(dev/test/prod)
spring:
#配置swagger2生产和测试环境不可用
profiles:
active: prod
使用maven package打包测试
运行测试
打开CMD,跳转到target目录,输入命令:java -jar .\xxx.jar --spring.profiles.active=prod。可以直接打开jar包修改application.yml配置文件中spring.profiles.active属性切换运行环境,具体请参考以下配置:
开发环境:dev;
生产环境:prod;
测试环境:test;
Swagger配置扫描接口
@ApiModel("用户实体类")
public class User {
@ApiModelProperty("用户名")
private String username;
@ApiModelProperty("密码")
private String password;
}
@RestController
public class HelloController {
@GetMapping("/hello")
public String hello(){
return "hello";
}
//只有当controller中的返回值是一个实体类对象,才显示在swagger中
@PostMapping("/user")
public User user(){
return new User();
}
@GetMapping("/hello1")
@ApiOperation("测试") //解释这个接口是干什么的
public String hello1(@ApiParam("用户名") String name){
return "hello"+name;
}
}
创建Swagger配置类
@Configuration
//开启Swagger2
@EnableSwagger2
//配置生产环境下不可用 dev(开发)、test(测试)、prod(生产)
@Profile({"dev","test"})
public class Swagger2Configuration extends WebMvcConfigurationSupport {
//api接口包扫描路径
public static final String
SWAGGER_SCAN_BASE_PACKAGE = "com.lky.swagger2pro.controller";
//指定当前Swagger API文档版本
public static final String VERSION = "1.0.0";
/**
* 创建API应用
* apiInfo() 增加API相关信息
* 通过select()函数返回一个ApiSelectorBuilder实例,用来控制哪些接口暴露给Swagger来展现,
* 本例采用指定扫描的包路径来定义指定要建立API的目录。
* @return
*/
@Bean
public Docket createRestApi() {
return new Docket(DocumentationType.SWAGGER_2)
// 接口文档的基本信息
.apiInfo(apiInfo())
.select()
// 方法需要有ApiOperation注解才能生存接口文档
//.apis(RequestHandlerSelectors.basePackage(SWAGGER_SCAN_BASE_PACKAGE))
.apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
// 路径使用any风格
.paths(PathSelectors.any())
.build();
}
/**
* 创建该API的基本信息(这些基本信息会展现在文档页面中)
* 访问地址:http://项目实际地址/doc.html
* @return
*/
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("SpringBoot中使用Swagger2构建RestFul APIs")
.description("测试系统")
//.termsOfServiceUrl("http://www.**.com")
.version(VERSION)
.build();
}
@Override
protected void addResourceHandlers(ResourceHandlerRegistry registry) {
registry.addResourceHandler("doc.html").addResourceLocations("classpath:/META-INF/resources/");
registry.addResourceHandler("/webjars/**").addResourceLocations("classpath:/META-INF/resources/webjars/");
}
建RestFul APIs")
.description(“测试系统”)
//.termsOfServiceUrl(“http://www.**.com”)
.version(VERSION)
.build();
}
@Override
protected void addResourceHandlers(ResourceHandlerRegistry registry) {
registry.addResourceHandler(“doc.html”).addResourceLocations(“classpath:/META-INF/resources/”);
registry.addResourceHandler(“/webjars/**”).addResourceLocations(“classpath:/META-INF/resources/webjars/”);
}