SpringBoot使用Swagger2
1.引入swagger依赖
<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.9.2</version>
</dependency>
2.添加swagger配置类
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
@Configuration
@EnableSwagger2
public class SwaggerConfig {
@Bean
public Docket createRestApi(){
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
//swagger文档扫描的包，这里扫描的是全部
//如果扫描指定包下的可以这样写
//.apis(RequestHandlerSelectors.basePackage("com.xxx.yyy.controller"))
.apis(RequestHandlerSelectors.any())
.paths(PathSelectors.any())
.build();
}
private ApiInfo apiInfo(){
return new ApiInfoBuilder()
.title("标题")
.description("描述")
.version("版本")
.termsOfServiceUrl("公司网址")
.build();
}
}
3.测试Controller
@RestController
@RequestMapping("/test")
public class TestController {
@GetMapping("/test01")
public String test01(){
return "test01";
}
@GetMapping("/test02")
public String test02(){
return "test02";
}
@GetMapping("/test03")
public String test03(){
return "test03";
}
}
4.测试
项目正常启动后浏览器输入网址
http://localhost:8100/swagger-ui.html#/
（这里的端口填写自己服务的端口，我的是8100，默认端口8080）
测试结果
5.swagger的注解
上面就是swagger的基本使用
但swagger也提供了一些注解，这里例举一些常用注解
Api注解
用于标记当前类为Swagger的文档资源。其中含有几个常用属性，分别说明如下。
• value：定义当前接口文档的名称。
• description：用于定义当前接口文档的介绍。
@Api(value = "controller接口",description = "用户测试接口")
public class TestController {
ApiOperation注解
@ApiOperation用在接口的方法上，主要用来注解请求接口。其中包含几个常用属性，分别说明如下。
• value：对API的简短描述。
• note：API的有关细节描述。
• hidden：如果值为true，就会在文档中隐藏。
演示
@GetMapping("/test01")
@ApiOperation(value = "测试方法01",notes = "细节的描述，细节的测试",hidden = false)
public String test01(){
return "test01";
}
ApiImplicitParam、ApiImplicitParams注解
使用在API请求方法上，@ApiImplicitParams的子集是@ApiImplicitParam注解，其中@ApiImplicitParam注解常用参数。
• name：参数的名称。
• value：参数值。
• required：如果值为true，就是必传字段。
• defaultValue：参数的默认值。
• dataType：数据的类型。
演示
@GetMapping("/test02")
@ApiImplicitParams(value = {
@ApiImplicitParam(name = "name",value = "测试姓名",required = false,defaultValue = "默认姓名李四"),
@ApiImplicitParam(name = "age",value = "测试年龄",required = false,dataType = "Integer",defaultValue = "200")
})
public String test02(String name,Integer age){
return "test02 姓名："+name+" 年龄:"+age;
}
ApiParam注解
ApiParam用于方法的参数，其中包含以下几个常用属性。
• name：参数的名称。
• value：参数值。
• required：如果值为true，就是必传字段。
• defaultValue：参数的默认值。
• type：参数的类型。
• hidden：如果值为true，就隐藏这个参数。
与ApiImplicitParam、ApiImplicitParams注解类似，不再赘述。
ApiResponse、ApiResponses注解
@ApiResponses和@ApiResponse二者配合使用返回HTTP状态码。@ApiResponses的value值是@ApiResponse的集合，多个@ApiResponse用逗号分隔。其中，@ApiResponse常用参数如下。
• code：HTTP状态码。
• message：HTTP状态信息。
• responseHeaders：HTTP响应头。
演示
@GetMapping("/test03")
@ApiResponses(value = {
@ApiResponse(code = 200,message = "成功"),
@ApiResponse(code = 404,message = "异常")
})
public String test03(){
return "test03";
}
ResponseHeader注解
如果需要设置响应头，就将@ResponseHeader设置到@ApiResponse的responseHeaders参数中。@ResponseHeader提供了以下几个参数。
• name：响应头名称。
• description：响应头描述。
ApiModel、ApiModelProperty注解
设置API响应的实体类，用作API返回对象。@ApiModel常用参数。
• value：实体类名称。
• description：实体类描述。
设置API响应实体的属性，其中常用参数。
• name：属性名称。
• value：属性值。
演示
@ApiModel(value = "Student(学生类)",description = "记录学生个人信息")
public class Student {
public String name;
@ApiModelProperty(name = "age",value = "年龄")
public Integer age;
}
6.更多
本文总结粗略
更多详细使用参照swagger官网