Swagger是一个自动生成API文档的 框架,避免了传统的手动编写API文档,然后再发给前段的繁琐。
首先:
1、新建一个Sping boot项目,引入以下依赖:
<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>
2、Swagger配置类:
@Configuration
@EnableSwagger2
public class Swgger2Configuration {
@Bean
public Docket createSwagger2Api(){
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
.apis(RequestHandlerSelectors.basePackage("com.cn.spring.cloud.jennire.microservice"))
.paths(PathSelectors.any())
.build();
}
private ApiInfo apiInfo(){
return new ApiInfoBuilder()
.title("swagger测试")
.description("简单容易的API接口文档")
.version("1.0")
.build();
}
}
配置类上需要 有@Configuration 和 @EnableSwagger2 注解 ,需要一个返回Docket的被@Bean注释的 方法,名字随意取。
此方法中,new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo()) ..... ; apiInfo()方法,执行了Swagger的一些基本信息,这些都是开发人员自己指定;
3、在Application上加EnableSwagger2注解 ,开启Swagger:
@SpringBootApplication
@EnableSwagger2
public class MicroserviceApplication {
public static void main(String[] args) {
SpringApplication.run(MicroserviceApplication.class, args);
}
}
4、在接口上加入Swagger:
@RestController
public class HelloController {
@ApiOperation(value="测试API",notes = "API工具")
@GetMapping("/hello")
public String index(@RequestBody User user){
return "hello";
}
}
上面的接口有一个User 对象,User对象的参数也可以用Swagger来注释:
@Getter
@Setter
@Builder
@ApiModel(description = "请求参数实体")
public class User implements Serializable {
@ApiModelProperty(value = "用户名称",required = true)
private String name;
@ApiModelProperty(value = "用户性别" ,required = true)
private String sex;
@ApiModelProperty(value = "用户年龄",required = true)
private int age;
}
@Getter 和@Setter 、 @Builder 注解 是实现了类中参数的 get set 方法, Builder 是 实现了构建器的方式来 访问和实例化是对象,只需要引入以下依赖:
<dependency>
<groupId>org.projectlombok</groupId>
<artifactId>lombok</artifactId>
<version>1.16.20</version>
</dependency>
接下来启动项目,访问localhost:8080/swagger-ui.html;
Swagger中注解说明:
@Api():作用于类上,表示这个类是swagger的资源。
tags = ”说明该类的作用“
@ApiOperation():用在请求的方法上,说明的方法的用户和作用
value=“说明方法的用途、作用”
notes="方法的备注说明“
@ApiImplicitParams():用在请求的方法上,表示一组参数说明,可以包含多个@ApiImplicitParam()
@ApiImplicitParam():指定一个请求参数的各个方面
name:参数名
value:参数的汉字说明
required:参数是否必须传
dataType:参数类型
defaultValue:参数的默认值
@ApiResponses():用在请求的方法上,表示一组响应。可以包含多个@ApiResponse()
@ApiResponse():用于表示一个错误的响应信息
code:数字
message:信息
response:抛出异常的类
@ApiModel():用在响应类上,表示一个返回响应数据的信息。
@ApiModelProperty():用在属性上,描述响应类的属性