1.什么是Swagger
Swagger 是一个规范和完整的框架,用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。
功能:1.接口的文档在线生成 2.功能测试
2.导入Maven
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.9.2</version>
</dependency>
//swagger图形化界面ui
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.9.2</version>
</dependency>
3.创建Swagger配置类
createRestApi():
创建API应用apiInfo() 增加API相关信息通过select()函数返回一个ApiSelectorBuilder实例,用来控制哪些接口暴露给Swagger来展现,
注:apis(RequestHandlerSelectors.basePackage("controller的包路径")
apiInfo():
创建API的基本信息(Swagger页面头部显示)
Swagger2 配置类如下
@Configuration
@EnableSwagger2
public class Swagger2 {
@Bean
public Docket createRestApi(){
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
.apis(RequestHandlerSelectors.basePackage("com.joker.jokerswagger2.controller"))
.paths(PathSelectors.any())
.build();
}
private ApiInfo apiInfo(){
return new ApiInfoBuilder()
.title("Spring Boot中使用Swagger2构建RESTful APIs")
.description("更多Spring Boot相关文章请关注:XXXXXXXXXXXXXXXXX")
.termsOfServiceUrl("http://www.baidu.com/")
.contact("Joker")
.version("2.0.0")
.build();
}
}
4.Swagger使用注解及其说明(文档内容说明及描述)
@Api :用在类上,说明该类的作用。
@ApiOperation :注解来给API增加方法说明。
@ApiImplicitParams : 用在方法上包含一组参数说明。
说明:
paramType:指定参数放在哪个地方
header:请求参数放置于Request Header,使用@RequestHeader获取
query:请求参数放置于请求地址,使用@RequestParam获取
path:(用于restful接口)-->请求参数的获取:@PathVariable
body:(不常用)
form(不常用)
name:参数名
dataType:参数类型
required:参数是否必须传
value:说明参数的意思
defaultValue:参数的默认值
@ApiImplicitParam:用来注解给方法入参增加说明。
@ApiResponses:用于表示一组响应
@ApiResponse:用在@ApiResponses中,一般用于表达一个错误的响应信息
l code:数字,例如400
l message:信息,例如"请求参数没填好"
l response:抛出异常的类
@ApiModel:描述一个Model的信息(一般用在请求参数无法使用@ApiImplicitParam注解进行描述的时候)
l @ApiModelProperty:描述一个model的属性
5.创建Controller测试
@RestController
@RequestMapping("/hello")
@Api(tags = "swagger测试Controller")
public class HelloController {
@ApiOperation("人间失格")
@GetMapping("/world")
public String world(){
return "我于昨夜死去,去时心如止水、我于今早重生,来时心怀暖阳";
}
@ApiOperation("太华")
@PostMapping("/taiHua")
public String taiHua(){
return "既御鲲鹏而厌江离、又乘扶摇以上青云.";
}
@GetMapping("/yuWen")
@ApiOperation("驭文")
public String yuWen(){
return "驭文之首术、谋篇之大端";
}
}
6.浏览器访问
http://localhost:8080/swagger-ui.html
打开Swagger图形化界面