0、 swagger简介
swagger是一个功能强大的api框架
,它的集成非常简单,不仅提供了在线文档的查阅
,而且还提供了在线文档的测试
。另外swagger很容易构建restful风格的api,简单优雅帅气,正如它的名字。
简单的来说,Swagger2的诞生就是为了解决前后端开发人员进行交流的时候API文档难以维护的痛点,它可以和我们的Java程序完美的结合在一起,并且可以与我们的另一开发利器Spring Boot来配合使用。
一、导入pom依赖
<!--api框架 在线文档的查阅,测试-->
<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.6.1</version>
</dependency>
或者
<!-- 这里使用 swagger-bootstrap-ui 替代了原有丑陋的ui,拯救处女座~ -->
<dependency>
<groupId>com.github.xiaoymin</groupId>
<artifactId>swagger-bootstrap-ui</artifactId>
<version>1.9.0</version>
</dependency>
二、 添加配置类
我们需要新增一个Swagger2Config 的配置类,apiINfo()配置一些基本的信息
。apis()指定扫描的包会生成文档
:
@Configuration
@EnableSwagger2
public class Swagger2Config {
@Bean
public Docket createRestApi() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
//这里把扫描的包配置一下
.apis(RequestHandlerSelectors.basePackage("com.wxmanage.address.controller"))
.paths(PathSelectors.any())
.build();
}
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("springboot利用swagger构建api文档")
.description("简单优雅的restfun风格,https://blog.csdn.net/qq_35456400")
.termsOfServiceUrl("https://blog.csdn.net/qq_35456400")
.version("1.0")
.build();
}
}
三、写注解
使用第一种UI访问地址:http://localhost:8080/swagger-ui.html
使用第二种UI访问地址:http://localhost:8080/doc.html
注意是再你配置的包下面的类中
- @Api,修饰整个类,描述Controller的作用
属性 | 作用 |
---|---|
tags | 说明该类的作用 |
value | 说明该类的作用 |
@Api(value = "操作机构",tags = "操作机构信息")
@Log
@RestController
public class InstController {
...
}
- @ApiOperation ,描述一个类的一个方法,或者说一个接口
| 属性 | 作用 |
|–|--|
| value | 描述方法作用 |
|notes | 提示内容 |
| tags | 分组 | - @ApiParam:单个参数描述,多个用@ApiImplicitParams
属性 | 作用 |
---|---|
name | 参数名 |
value | 参数说明 |
required | 是否必填 |
@ApiOperation(value="发送删除机构信息到微信后台", notes="发送删除机构信息到微信后台")
@GetMapping("/deleteInst")
public String deleteInst(@ApiParam(name="id",value="用户id",required=true) Long id){
}
- @ApiModel && @ApiModelProperty
@ApiModel:用对象来接收参数,修饰类
属性 | 作用 |
---|---|
value | 对象名 |
description | 描述 |
@ApiProperty:用对象接收参数时,描述对象的一个字段,修饰属性
属性 | 作用 |
---|---|
value | 字段说明 |
name | 属性名 |
dataType | 属性类型 |
required | 是否必填 |
example | 举例 |
hidden | 隐藏 |
@ApiModel(value="user对象",description="用户对象user")
@Data
public class User {
@ApiModelProperty(value = "用户ID",example = "1000001",hidden=true)
private Long id;
@ApiModelProperty(value="用户名",required = true,dataType = "String")
private String userName;
@ApiModelProperty(value = "密码")
private String password;
}
- @ApiImplicitParam && @ApiImplicitParams
@ApiImplicitParam :一个请求参数·
属性 | 作用 |
---|---|
value | 参数说明 |
name | 参数名 |
dataType | 数据类型 |
paramType | 参数类型 |
example | 举例 |
@ApiImplicitParams多个请求参数
@ApiImplicitParams({
@ApiImplicitParam(name="access_token", value = "应用的token", required = true, dataType = "String"),
@ApiImplicitParam(name="id")
})
@GetMapping("/deleteInst")
public String deleteInst(String access_token,String id){
...
}
- @ApiResposne && @ApiResponses
@ApiResponse:HTTP响应其中1个描述
属性 | 作用 |
---|---|
response | 返回类 |
code | 返回码 |
message | 返回信息 |
examples | 例子 |
@ApiResponses:HTTP响应整体描述
- @ApiIgnore:使用该注解忽略这个API·
- @ApiError :发生错误返回的信息
四、 两种UI风格对比
spring-fox的ui
http://localhost:8080/swagger-ui.html
bootstrap风格的ui:
http://localhost:8080/doc.html