最近换了新团队,之前都是使用rap作为接口管理工具,个人感觉还是挺好用的。新团队是全部spring cloud的架构,准备开始学习使用swagger作为管理平台。swaggerHub看起来也是融合了多种工具,包括swagger editor, swagger ui, swagger codegen。本来是想用swagger editor(与rap功能类似)用来编辑接口文档的,奈何网络环境问题,无法安装。就先研究了下swagger ui。
一. 添加依赖
<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>
第二种配置方式,好像需要spring-boot版本要高于2.0以上(未深入研究,不是十分确定)
<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger2 -->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.9.2</version>
</dependency>
二.配置和加注解
@Configuration
@EnableSwagger2 // 启用 Swagger
public class SwaggerConfig {
@Bean
public Docket createRestApi() {
return new Docket(DocumentationType.SWAGGER_2)
.select()
.apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
.paths(PathSelectors.any())
.build().enable(true);
}
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("部门列表请求")
.version("1.0")
.build();
}
}
三. 配置api接口
@Api和@ApiOperation(value = “获取部门信息”) 都是
@Api(value = "部门管理")
@RestController
@RequestMapping(value = "/dept")
public class DeptController {
private DeptService deptService;
@Autowired
public void setDeptService(DeptService deptService) {
this.deptService = deptService;
}
@ApiOperation(value = "获取部门信息")
@GetMapping("get/{id}")
public Dept getDept(@PathVariable int id) {
return deptService.get(id);
}
@ApiOperation(value = "获取部门列表")
@GetMapping("list/")
public List<Dept> getList() {
return deptService.getList();
}
@ApiOperation(value = "添加部门")
@PostMapping("addDept/")
public void addDept(Dept dept) {
deptService.addDept(dept);
}
}
四. 运行,访问
启动项目,访问地址localhost:port/swagger-ui.html,就能看到如下页面,看起来很清晰,可以增加接口描述等各类信息,还可以mock。唯一不足之处需要启动服务之后,才可以访问,并且是写完代码之后才会生成。不适用于提前确定接口报文。我感觉其作用更多的是对现有接口的文档维护。而想要和前端约定报文的话,可以使用swagger editor。有机会的话,我再研究研究。
五.附录
附上一些api介绍:
@Api:用在类上,说明该类的作用。
@ApiOperation:注解来给API增加方法说明。
@ApiImplicitParams : 用在方法上包含一组参数说明。
@ApiImplicitParam:用来注解来给方法入参增加说明。
参数:
·paramType:指定参数放在哪个地方
··header:请求参数放置于Request Header,使用@RequestHeader获取
··query:请求参数放置于请求地址,使用@RequestParam获取
··path:(用于restful接口)-->请求参数的获取:@PathVariable
··body:(不常用)
··form(不常用)
·name:参数名
·dataType:参数类型
·required:参数是否必须传(true | false)
·value:说明参数的意思
·defaultValue:参数的默认值
@ApiResponses:用于表示一组响应
@ApiResponse:用在@ApiResponses中,一般用于表达一个错误的响应信息
——code:数字,例如400
——message:信息,例如"请求参数异常!"
——response:抛出异常的类
@ApiModel:描述一个Model的信息(一般用在请求参数无法使用@ApiImplicitParam注解进行描述的时候)
@ApiModelProperty:描述一个model的属性