Spring Boot整合Swagger-ui开发接口api文档
文章目录
前言
使用spring boot对swagger进行整合,并使用合适的注解对接口进行说明注释,本文主要是对使用swagger的一个记录。
一、添加swagger依赖和配置
1.添加maven依赖
maven依赖如下:
<!-- swagger 依赖-->
<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>
2.添加swagger配置类
配置类代码如下:
@Configuration
@EnableSwagger2
public class SwaggerConfig {
@Bean
public Docket createRestApi() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
//扫描的包文件目录
.apis(RequestHandlerSelectors.basePackage("com.permission"))
.paths(PathSelectors.any())
.build();
}
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("xxx")//文档标题
.description("xxx")//文档描述
//此处原先的contact(String)的方法已经弃用,需要构造一个新的Contact对象
.contact(new Contact("name","url","email"))//文档作者详情
.version("1.0")//版本
.build();
}
}
二、使用swagger注解
此步骤可以不做,但是不做的话会导致接口文档没有中文说明。
1.针对实体类
使用@ApiModel() 和@ApiModelProperty()
示例代码如下:
@ApiModel("测试vo")
public class TestVo {
@ApiModelProperty("名字")
private String name;
@ApiModelProperty("性别")
private String sex;
}
2.针对controller层的接口
使用@Api、@ApiOperation和@ApiParam居多,还有就是@ApiResponse和@ApiResponses
示例代码如下:
@Api(value = "测试接口",description = "测试接口")
@RestController
public class TestController {
@ApiOperation(value = "hello接口",notes = "传入String类型的参数",response = TestVo.class)
@GetMapping("/hello")
public TestVo hello(@ApiParam("姓名") String name){}
//一般上述的注解就可以适用于大多数地方
//@ApiResponses就是包含了多个@ApiResponse,写法如下,还有其它的一些参数,但本人未使用过。
@ApiResponses({
@ApiResponse(code = 200,message = "正常",response = TestVo.class)
})
}
三、页面效果
1.进入swagger的ui界面
//路径示例
http://localhost:8080/swagger-ui.html
2.效果展示
只用在实体类中用对应的注解,才会展示对应的字段提示