Swagger™的目标是为REST API 定义一个标准的，与语言无关的接口，使人和计算机在看不到源码或者看不到文档或者不能通过网络流量检测的情况下能发现和理解各种服务的功能。当服务通过Swagger定义，消费者就能与远程的服务互动通过少量的实现逻辑。
简单说，swagger能够根据代码中的注释自动生成api文档，并且提供测试接口；
swagger和swagger2是两个不同的版本，现在用的比较多的是swagger和springfox，springfox就是swagger-springmvc的升级版，也叫swagger2；
使用springfox；
集成springfox和springmvc:
//添加依赖
<!-- swagger2 start -->
<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>
<!-- swagger2 end -->
@Configuration
@EnableSwagger2
public class ApiConfig {
@Bean
public Docket docket() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
.apis(RequestHandlerSelectors.basePackage("cn.wolfcode"))//扫描路径
// .apis(RequestHandlerSelectors.withMethodAnnotation(ApiImplicitParams.class))//根据注解定制
.paths(PathSelectors.any()) //定义哪些路径的接口需要生成文档
.build();
}
@Bean
public ApiInfo apiInfo() {
Contact contact = new Contact("sky","https://www.jianshu.com/u/a099a2677722","8888@126.com");
return new ApiInfoBuilder()
.title("Spring Boot中使用Swagger2构建RESTful API")//文档首页标题
.description("swagger2-文档构建利器")//文档描述信息
.contact(contact) //创建者信息
.version("1.0") //文档版本
.build();
}
}
访问地址:http://localhost:8080/v2/api-docs
ui访问地址:http://localhost:8080/swagger-ui.html
springfox的标签:
@Api(value = "用户增删改查",description = "详细描述")
@RestController
@RequestMapping("/users")
public class EmpController {
//获取用户列表
@ApiOperation(value = "获取用户列表",notes = "获取用户列表详细描述")
@GetMapping
public List<Emp> getUsers(){
List list = new ArrayList<>();
list.add(new Emp(1L,"A"));
list.add(new Emp(2L,"B"));
list.add(new Emp(3L,"C"));
return list;
}
//获取用户
/*
params = "pwd=999"
headers = "Content-Type=application/json" == "Accept=application/json"
headers="contentType=application/json" == consumes="application/json"
*/
@RequestMapping(value = "/{id}",method = RequestMethod.GET)
public Emp getUser(@PathVariable("id") Long id){
System.out.println("id : "+id);
return new Emp(1L,"xx");
}
//删除用户
@ApiImplicitParams({
@ApiImplicitParam(name = "id",value = "用户的唯一标识",required = true),
@ApiImplicitParam(name = "name" ,value = "用户名" , required = false)
})
@ApiResponses({
@ApiResponse(code = 401 ,message = "禁止访问")
})
@DeleteMapping("/{id}/{name}")
public void deleteUsers(@PathVariable("id") Long id ,@PathVariable("name") String name){
System.out.println("删除成功...");
}
//创建用户
@ApiIgnore
@PostMapping
public Emp createUsers(@RequestBody Emp emp){
System.out.println(emp);
return emp;
}
}
swagger2优点: 简单 , 实时 , 可测试 , 容易管理
swagger2缺点: 代码侵入性太强, 影响正常代码阅读
学习swagger2就是学习怎么使用注解为接口添加描述信息
@Api：修饰整个类，描述Controller的作用
@ApiOperation：描述一个类的一个方法，或者说一个接口
@ApiImplicitParams：多个请求参数
@ApiImplicitParam：一个请求参数
@ApiResponses：HTTP响应整体描述
@ApiResponse：HTTP响应其中1个描述
@ApiModel：用对象来接收参数
@ApiModelProperty：用对象接收参数时，描述对象的一个字段
@ApiIgnore：使用该注解忽略这个API
类和方法的描述:
@Api修饰整个类，描述Controller的作用
@ApiOperation 贴在方法上,描述一个方法的作用
1、@Api注解的使用：贴在类上，主要用下面的这几个属性
1）value：该controller简短的标题
2）description：详细介绍
3）producer：说明该controller是使用什么显示层格式的
4）protocols：使用什么协议
2、@ApiOperation注解的使用：贴在方法上，主要用下面的这几个属性
1）value：该方法简短的变态
2）note：详细介绍
3）code：正常情况下返回的状态码是多少
4）httpMethod：使用什么http方法
5）response：响应什么对象，这里写的是响应的对象的字节码
/**
*
* @param param
* @return
*/
@ApiOperation(value = "获取所有产品信息", notes = "获取所有产品信息", httpMethod = "GET")
@ResponseBody
@RequestMapping(value="/sync/test", method = RequestMethod.GET)
public JSONMessage test(String value,String notes) {
return JSONMessage.success("测试功能");
}
参数的描述:
贴在参数上
@ApiImplicitParams 多个请求参数
@ApiImplicitParam 一个请求参数
@ApiParam 单个参数描述
1）name:参数名
2）value:参数名对应的值
3）dataType：参数的类型
4）require：该参数是否必填
5）paramType：该参数的来源类型，它的值有如下：
query：该参数从地址栏问号后面的参数获取
form：该参数从form表单中获取
path：该参数从URL地址上获取
body：该参数从请求体中获取
header：该参数从请求头获取
响应的描述:
@ApiResponses：HTTP响应整体的描述
@ApiResponse：HTTP响应中某一种响应的描述
用在@ApiResponses中，一般用于表达一个错误的响应信息(200相应不写在这里面)
code：数字，例如400
message：信息，例如"请求参数没填好"
response：抛出的异常类
对象模型描述:
@ApiModel/@ApiModelProperty
@ApiModel：描述一个Model的信息（这种一般用在post创建的时候，使用@RequestBody这样的场景，请求参数无法使用@ApiImplicitParam注解进行描述的时候）
@ApiModelProperty：描述一个model的属性
忽略接口API:
@ApiIgnore 贴了该注解的api 会被忽略,不生成接口文档
两种不生成api的方式：
1、@ApiIgnore：可以贴在类和方法上
2、在swagger配置类上的select()方法上调用apis(),apis方法需要传入一个selector。可以使用RequestHandlerSelector内置的selector
springBoot集成swagger2:
//添加依赖
<!-- swagger2 start -->
<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>
<!-- swagger2 end -->
@Configuration
@EnableSwagger2
public class SwaggerConfig{
@Bean
public Docket createRestApi() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
// .apis(RequestHandlerSelectors.basePackage("cn.wolfcode.controller"))//扫描路径
.apis(RequestHandlerSelectors.withMethodAnnotation(ApiImplicitParams.class))//根据注解定制
.paths(PathSelectors.any()) //定义哪些路径的接口需要生成文档
.build();
}
@Bean
private ApiInfo apiInfo() {
Contact contact = new Contact("sky","https://www.jianshu.com/u/a099a2677722","8888@126.com");
return new ApiInfoBuilder()
.title("Spring Boot中使用Swagger2构建RESTful API")//文档首页标题
.description("swagger2-文档构建利器")//文档描述信息
.contact(contact) //创建者信息
.version("1.0") //文档版本
.build();
}
}
网友评论