Swagger 2.9.2
Swagger介绍
发现了痛点就要去找解决方案。解决方案用的人多了，就成了标准的规范，这就是Swagger的由来。通过这套规范，你只需要按照它的规范去定义接口及接口相关的信息。再通过Swagger衍生出来的一系列项目和工具，就可以做到生成各种格式的接口文档，生成多种语言的客户端和服务端的代码，以及在线接口调试页面等等。这样，如果按照新的开发模式，在开发新版本或者迭代版本的时候，只需要更新Swagger描述文件，就可以自动生成接口文档和客户端服务端代码，做到调用端代码、服务端代码以及接口文档的一致性。
但即便如此，对于许多开发来说，编写这个yml或json格式的描述文件，本身也是有一定负担的工作，特别是在后面持续迭代开发的时候，往往会忽略更新这个描述文件，直接更改代码。久而久之，这个描述文件也和实际项目渐行渐远，基于该描述文件生成的接口文档也失去了参考意义。所以作为Java届服务端的大一统框架Spring，迅速将Swagger规范纳入自身的标准，建立了Spring-swagger项目，后面改成了现在的Springfox。通过在项目中引入Springfox，可以扫描相关的代码，生成该描述文件，进而生成与代码一致的接口文档和客户端代码。这种通过代码生成接口文档的形式，在后面需求持续迭代的项目中，显得尤为重要和高效。
框架说明
现在SWAGGER官网主要提供了几种开源工具，提供相应的功能。可以通过配置甚至是修改源码以达到你想要的效果。
Swagger Codegen: 通过Codegen 可以将描述文件生成html格式和cwiki形式的接口文档，同时也能生成多钟语言的服务端和客户端的代码。支持通过jar包，docker，node等方式在本地化执行生成。也可以在后面的Swagger Editor中在线生成。
Swagger UI:提供了一个可视化的UI页面展示描述文件。接口的调用方、测试、项目经理等都可以在该页面中对相关接口进行查阅和做一些简单的接口请求。该项目支持在线导入描述文件和本地部署UI项目。
Swagger Editor: 类似于markendown编辑器的编辑Swagger描述文件的编辑器，该编辑支持实时预览描述文件的更新效果。也提供了在线编辑器和本地部署编辑器两种方式。
Swagger Inspector: 感觉和postman差不多，是一个可以对接口进行测试的在线版的postman。比在Swagger UI里面做接口请求，会返回更多的信息，也会保存你请求的实际请求参数等数据。
Swagger Hub：集成了上面所有项目的各个功能，你可以以项目和版本为单位，将你的描述文件上传到Swagger Hub中。在Swagger Hub中可以完成上面项目的所有工作，需要注册账号，分免费版和收费版。
PS：
Springfox Swagger: Spring 基于swagger规范，可以将基于SpringMVC和Spring Boot项目的项目代码，自动生成JSON格式的描述文件。本身不是属于Swagger官网提供的，在这里列出来做个说明，方便后面作一个使用的展开。
初步使用
起步：创建springboot工程、引入web模块、编写一个hello请求
1.引入srpingfox依赖
<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger2 --> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger2</artifactId> <version>2.9.2</version> </dependency> <!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger-ui --> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger-ui</artifactId> <version>2.9.2</version> </dependency>
[注]
1.使用swagger要求jdk1.8及以上，否则swagger2不能运行
2.springboot集成swagger需要引入两个包即以上两个
2.配置Swagger
@Configuration
@EnableSwagger2 //开启swagger2
public class SwaggerConfig {
}
[注]
1.此时swagger其实已经可以访问了，不用任何配置
3.运行测试
访问：http://localhost:8080/swagger-ui.html
进阶：简单使用
配置swagger封面信息
@Bean
public Docket docket(){
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo());
}
private ApiInfo apiInfo(){
//作者信息
Contact contact = new Contact("Ferao", "https://blog.csdn.net/qq_21561501", "928971634@qq.com");
return new ApiInfo(
"Ferao的swaggerAPI文档",
"11",
"v1.0",
"https://blog.csdn.net/qq_21561501",
contact,
"Apache2.0",
"https://blog.csdn.net/qq_21561501",
new ArrayList()
);
}
[注]
1.swagger实例bean是Docket，所以通过配置Docket实例来配置Swagger
2.apiInfo()是配置文档的基础信息
效果图示例
进阶配置：扫描接口
@Bean
public Docket docket(){
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
//是否启动swagger 如果是false则不能在浏览器中使用
.enable(true)
.select()
//RequestHandlerSelectors. 配置要扫描的方式
//basePackage():指定要扫描的包
//any():扫描全部
//none()：不扫描
//withClassAnnotation():扫描类上的注解，参数是一个注解的反射对象
//withMethodAnnotation():扫描方法上的注解
.apis(RequestHandlerSelectors.basePackage("com.ferao.controller"))
//.paths() .过滤URL
//any() 任何请求都扫描
//none() 任何请求都不扫描
//ant() 通过ant控制
//regex() 通过正则表达式控制
.paths(PathSelectors.ant("/ferao/**"))
.build();
}
需求：只希望swagger在生产环境中使用，在发布的时候不使用
分析：
1.判断是不是生产环境 flag=false
2.注入enable(flag)
@Configuration
@EnableSwagger2 //开启swagger2
public class SwaggerConfig {
//配置swagger的Docket的bean实例
@Bean
public Docket docket(Environment environment){
//设置要显示的swagger环境
Profiles profiles = Profiles.of("dev", "test");
//通过environment.acceptsProfiles判断是否处于自己设定的环境中
boolean flag = environment.acceptsProfiles(profiles);
return new Docket(DocumentationType.SWAGGER_2)
.groupName("Ferao-group")
.apiInfo(apiInfo())
.enable(flag)
.select()
//配置要扫描的接口
.apis(RequestHandlerSelectors.basePackage("com.ferao.controller"))
.paths(PathSelectors.ant("/users/**"))
.build();
}
//配置swagger信息=apiInfo
private ApiInfo apiInfo(){
//作者信息
Contact contact = new Contact("Ferao", "https://blog.csdn.net/qq_21561501", "928971634@qq.com");
return new ApiInfo(
"Ferao的swaggerAPI文档",
"11",
"v1.0",
"https://blog.csdn.net/qq_21561501",
contact,
"Apache2.0",
"https://blog.csdn.net/qq_21561501",
new ArrayList()
);
}
}
进阶配置：API分组
@Bean
public Docket docket1(){
return new Docket(DocumentationType.SWAGGER_2).groupName("group1");
}
@Bean
public Docket docket1(){
return new Docket(DocumentationType.SWAGGER_2).groupName("group1");
}
效果图示例
进阶配置：实体类描述
-
只要接口中返回值存在实体类，就会被swagger扫描
-
swagger页面给实体类Moel加注释
@Data
@NoArgsConstructor
@AllArgsConstructor
@ApiModel("User实体类")
public class User {
@ApiModelProperty("用户名")
private String username;
@ApiModelProperty("用户年龄")
private int age;
@ApiModelProperty("服务端设置")
private Date date;
}
效果图示例
请求接口名称描述
@ApiOperation(value = "1.根据全局变量获得author")
@GetMapping("/user")
public String getUsers(ModelMap modelMap){
System.out.println(modelMap.get("author"));
return "User-Messege";
}
效果图示例
请求接口参数描述
@ApiOperation(value = "1.根据全局变量获得author")
@ApiImplicitParams({
@ApiImplicitParam(name = "name", value = "名称", required = true, paramType = "query", dataType = "String")
})
@GetMapping("/user")
public String getUsers(String name){
return "User-Messege";
}
效果图示例
Responses返回类型描述
@ApiOperation(value = "1.根据全局变量获得author")
@ApiImplicitParams({
@ApiImplicitParams({
@ApiImplicitParam(name = "name", value = "名称", required = true, paramType = "query", dataType = "String")
})
})
@ApiResponses({
@ApiResponse(code=200,message="请求成功"),
@ApiResponse(code=500,message="系统异常")
})
@GetMapping("/user")
public String getUsers(String name){
return "User-Messege";
}
[注]
paramType=“body” 代表参数应该放在请求的什么地方：
header–>放在请求头。请求参数的获取：@RequestHeader(代码中接收注解)
query–>用于get请求的参数拼接。请求参数的获取：@RequestParam(代码中接收注解)
path（用于restful接口）–>请求参数的获取：@PathVariable(代码中接收注解)
body–>放在请求体。请求参数的获取：@RequestBody(代码中接收注解)
form（不常用）
dataType=“int” 代表请求参数类型为int类型，当然也可以是Map、User、String等；
接口文档实时更新解决了开发者之间即时交互作用很重要
注意在正式发布的时候，关闭swagger，出于安全考虑。而且节省运行的内存
浙公网安备 33010602011771号