先贴效果
image.png
- 右上角可以选择分组，每个分组下可以设标签管理api
- 每个api可以直接测试
1. maven dependency
新建maven项目，这里使用的是idea的Spring Initializr，勾选web依赖，就快速构建了SpringBoot项目，有了tomcat和发布RESTful API能力。
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-web</artifactId>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.9.2</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.9.2</version>
</dependency>
2. 配置swagger2
主要是构建Docket Bean，SwaggerConfig.java代码如下：
@Configuration
@EnableSwagger2
@Profile({"dev", "test"})
public class SwaggerConfig {
@Bean
public Docket apiGroup1() {
return new Docket(DocumentationType.SWAGGER_2)
.groupName("Group 1").tags(
new Tag("标签一", "描述")
, new Tag("标签二", "描述")
)
.apiInfo(this.getApiInfo("接口", "接口"))
.select()
.apis(RequestHandlerSelectors.any())
.paths(or(regex("/demo.*")))
.build();
}
private ApiInfo getApiInfo(String title, String desc) {
return new ApiInfo(
"XX系统 " + title + " API",
desc + " API文档",
"1.0",
"",
new Contact("联系我们", "", "mail@mail.com"),
"license",
"licenseUrl",
new ArrayList<>());
}
- @Profile({"dev", "test"}) 指明了只在dev和test profile运行时启用swagger，如实际项目运行prod profile时就不启用swagger
- .groupName可以不设，默认会有一个default的分组，实际项目中模块比较多，这个分组会比较实用，UI中右上角可以切换分组。 分组可以把多个tag组织在一起，通常是一个controler对应一个tag。需要加一个分组可以再建一个Docket Bean。
3. 新增Controller
package com.bq.demo.test;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiOperation;
import org.apache.catalina.User;
import org.springframework.web.bind.annotation.*;
@Api(value = "/demo/test", tags = "标签一")
@RestController
@RequestMapping("/demo/test")
public class TestSwaggerController {
@ApiOperation(value = "显示helloWorld", notes = "显示helloWorld")
@GetMapping("/helloWorld")
public Object showInfo() {
return "hello world";
}
@ApiOperation(value = "添加用户信息", notes = "添加用户信息")
@ApiImplicitParam(name = "user", value = "User", required = true, dataType = "User")
@PostMapping("/addUser")
public Object addUser(@RequestBody User user) {
return "success";
}
}
- 注意@Api中tags和上面group中的对应
- 标签二的Controller代码只是复制了一份，改了下@Api和@RequestMapping映射
- 打开 http://localhost:8080/swagger-ui.html 测试
