spring-boot 集成 Swagger2
This commit is contained in:
罗祥
parent
159051657d
commit
c9f2aec392
@ -16,6 +16,8 @@ spring-cloud：Finchley.SR2
|
||||
**更新日志**：
|
||||
|
||||
>2019.01.27 新增用例 : [spring boot + druid + mybatis + atomikos](https://github.com/heibaiying/spring-samples-for-all/tree/master/spring-boot/springboot-druid-mybatis-multi) 配置多数据源、支持分布式事务( JTA方式实现)
|
||||
>
|
||||
>2019.02.01 新增用例：[spring-boot-swagger2](https://github.com/heibaiying/spring-samples-for-all/tree/master/spring-boot/spring-boot-swagger2) spring-boot 集成 Swagger2 打造在线接口文档
|
||||
|
||||
## 1. spring samples
|
||||
|
||||
@ -62,8 +64,7 @@ spring-cloud：Finchley.SR2
|
||||
| [spring-boot-websocket](https://github.com/heibaiying/spring-samples-for-all/tree/master/spring-boot/spring-boot-websocket) | spring-boot 整合 websocket | [Using @ServerEndpoint](https://docs.spring.io/spring-boot/docs/2.1.1.RELEASE/reference/htmlsingle/#howto-create-websocket-endpoints-using-serverendpoint) |
|
||||
| [spring-boot-kafka](https://github.com/heibaiying/spring-samples-for-all/tree/master/spring-boot/spring-boot-kafka) | spring-boot 整合 kafka | [Apache Kafka Support](https://docs.spring.io/spring-boot/docs/2.1.1.RELEASE/reference/htmlsingle/#boot-features-kafka) |
|
||||
| [spring-boot-actuator](https://github.com/heibaiying/spring-samples-for-all/tree/master/spring-boot/spring-boot-actuator) | actuator + Hyperic SIGAR 应用信息监控 | [Spring Boot Actuator](https://docs.spring.io/spring-boot/docs/2.1.1.RELEASE/reference/htmlsingle/#production-ready) |
|
||||
|
||||
更多的用例可参阅 [spring-boot 官方samples ](https://github.com/spring-projects/spring-boot/tree/master/spring-boot-samples)
|
||||
| [spring-boot-swagger2](https://github.com/heibaiying/spring-samples-for-all/tree/master/spring-boot/spring-boot-swagger2) | spring-boot 集成 Swagger2 打造在线接口文档 | [Springfox Reference Documentation](http://springfox.github.io/springfox/docs/current/) |
|
||||
|
||||
<br/>
|
||||
|
||||
|
||||
BIN
pictures/Swagger_UI.png
Normal file
BIN
pictures/Swagger_UI.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 48 KiB |
BIN
pictures/swagger-execute.png
Normal file
BIN
pictures/swagger-execute.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 18 KiB |
BIN
pictures/swagger-post-try.png
Normal file
BIN
pictures/swagger-post-try.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 18 KiB |
BIN
pictures/swagger-try-it.png
Normal file
BIN
pictures/swagger-try-it.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 18 KiB |
BIN
pictures/swagger-ui-index.png
Normal file
BIN
pictures/swagger-ui-index.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 57 KiB |
BIN
pictures/swagger-ui-response.png
Normal file
BIN
pictures/swagger-ui-response.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 25 KiB |
266
spring-boot/spring-boot-swagger2/README.md
Normal file
266
spring-boot/spring-boot-swagger2/README.md
Normal file
@ -0,0 +1,266 @@
|
||||
# spring boot 整合 swagger 2.0
|
||||
## 目录<br/>
|
||||
<a href="#一Springfox-与-Swagger-简介">一、Springfox 与 Swagger 简介</a><br/>
|
||||
<a href="#11-Springfox">1.1 Springfox</a><br/>
|
||||
<a href="#12-Swagger">1.2 Swagger</a><br/>
|
||||
<a href="#13-OpenApiSwaggerSpringfox的关系">1.3 OpenApi、Swagger、Springfox的关系</a><br/>
|
||||
<a href="#二spring-boot-集成-swagger-20">二、spring boot 集成 swagger 2.0</a><br/>
|
||||
<a href="#21-导入项目相关依赖">2.1 导入项目相关依赖</a><br/>
|
||||
<a href="#22--进行swagger个性化配置并用EnableSwagger2开启Swagger支持">2.2 进行swagger个性化配置、并用@EnableSwagger2开启Swagger支持</a><br/>
|
||||
<a href="#23-swagger注解的使用和说明">2.3 swagger注解的使用和说明</a><br/>
|
||||
<a href="#24-swagger-ui-可视化接口文档">2.4 swagger-ui 可视化接口文档</a><br/>
|
||||
<a href="#25-利用swagger-ui进行接口测试">2.5 利用swagger-ui进行接口测试</a><br/>
|
||||
## 正文<br/>
|
||||
|
||||
## 一、Springfox 与 Swagger 简介
|
||||
|
||||
### 1.1 Springfox
|
||||
|
||||
Springfox 是一个开源的API Doc的框架， 它的前身是swagger-springmvc，能够完美的支持springmvc和swagger，可以将spring 接口方法自动转换为接口文档。 目前spring fox 正致力于对更多JSON API规范和标准的扩展和支持，例如：[swagger](http://swagger.io/)，[RAML](http://raml.org/)和[jsonapi](http://jsonapi.org/)。
|
||||
|
||||
### 1.2 Swagger
|
||||
|
||||
Swagger是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务，支持从整个API生命周期（从设计和文档到测试和部署）的开发。
|
||||
|
||||
swagger 是一个综合的开源项目，包含[swagger-core](https://github.com/swagger-api/swagger-core)、[swagger-ui](https://github.com/swagger-api/swagger-ui)、[swagger-codegen](https://github.com/swagger-api/swagger-codegen)、[swagger-editor](https://github.com/swagger-api/swagger-editor)等多个子项目。
|
||||
|
||||
+ **swagger-core**：Swagger Core是OpenAPI规范（以前称为Swagger规范）的**Java实现**。
|
||||
|
||||
+ **swagger-ui**：依据可视化文档，提供与API资源的可视化交互。
|
||||
|
||||
+ **swagger-codegen**：开源的代码生成器,根据Swagger定义的RESTful API可以自动建立服务端和客户端的连接。
|
||||
|
||||
+ **swagger-editor**：开源的api文档编辑器。
|
||||
|
||||
下图为swagger-ui 提供的文档可视化界面示例：
|
||||
|
||||
<div align="center"> <img src="https://github.com/heibaiying/spring-samples-for-all/blob/master/pictures/Swagger_UI.png"/> </div>
|
||||
|
||||
|
||||
|
||||
### 1.3 OpenApi、Swagger、Springfox的关系
|
||||
|
||||
**Swagger Core 是 OpenApi 规范（以前称为Swagger规范）的Java 实现，而 Springfox 提供 Swagger 与 spring 的集成支持**。
|
||||
|
||||
|
||||
|
||||
## 二、spring boot 集成 swagger 2.0
|
||||
|
||||
### 2.1 导入项目相关依赖
|
||||
|
||||
```xml
|
||||
<!--swagger2-->
|
||||
<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>
|
||||
```
|
||||
|
||||
|
||||
|
||||
### 2.2 进行swagger个性化配置、并用@EnableSwagger2开启Swagger支持
|
||||
|
||||
这里需要说明的是swagger虽然是一个非常直观易用的接口调试插件，但是有可能导致接口信息泄露的危险，所以建议在开发环境和测试环境开启，在生产环境关闭。这里一共给出三种Swagger开关切换的方法：
|
||||
|
||||
1. 如下面代码所示，在配置文件中配置自定义的开关参数，并在创建Docket时候，在链式调用的enable()方法中传入；
|
||||
|
||||
2. 在`SwaggerConfig`配置类上添加`@Profile({"dev","test"}) `注解，指明在开发环境和测试环境下激活此配置类，打包或者部署时候使用spring.profiles.active指明环境即可；
|
||||
|
||||
3. 在配置文件中配置自定义的开关参数，并在在`SwaggerConfig`配置类上添加`@ConditionalOnProperty(name = "swagger.enable", havingValue = "true") `，指明配置类的生效条件
|
||||
|
||||
注：@ConditionalOnProperty 注解说明
|
||||
|
||||
@ConditionalOnProperty注解能够控制某个@configuration修饰的配置类是否生效。具体操作是通过name和havingValue属性来实现，name对应application.properties（yml）中的某个属性值，如果该值为空，则返回false；如果值不为空，则将该值与havingValue指定的值进行比较，如果一样则返回true；否则返回false。如果返回值为false，则该configuration不生效；为true则生效。
|
||||
|
||||
```java
|
||||
/**
|
||||
* @author : heibaiying
|
||||
* @description : Swagger 配置类
|
||||
*/
|
||||
@Configuration
|
||||
@EnableSwagger2
|
||||
public class SwaggerConfig {
|
||||
|
||||
@Value("${swagger.enable}")
|
||||
private boolean swaggerEnable;
|
||||
|
||||
/***
|
||||
* 配置swagger
|
||||
* 开发和测试环境下可以开启swagger辅助进行调试,而生产环境下可以关闭或者进行相应的权限控制，防止接口信息泄露
|
||||
*/
|
||||
@Bean
|
||||
public Docket createRestApi() {
|
||||
return new Docket(DocumentationType.SWAGGER_2)
|
||||
.enable(swaggerEnable)
|
||||
.apiInfo(apiInfo())
|
||||
.select()
|
||||
.apis(RequestHandlerSelectors.basePackage("com.heibaiying.springboot.controller"))
|
||||
.paths(PathSelectors.any())
|
||||
.paths(doFilteringRules())
|
||||
.build();
|
||||
}
|
||||
|
||||
/***
|
||||
* 接口文档的描述信息
|
||||
*/
|
||||
private ApiInfo apiInfo() {
|
||||
return new ApiInfoBuilder()
|
||||
.title("spring boot swagger2 用例")
|
||||
.description("描述")
|
||||
.licenseUrl("https://mit-license.org/")
|
||||
.version("1.0")
|
||||
.build();
|
||||
}
|
||||
|
||||
/**
|
||||
* 可以使用正则定义url过滤规则
|
||||
*/
|
||||
private Predicate<String> doFilteringRules() {
|
||||
return not(
|
||||
regex("/ignore/*")
|
||||
);
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
application.properties :
|
||||
|
||||
```properties
|
||||
#swagger启用开关
|
||||
swagger.enable = true
|
||||
```
|
||||
|
||||
|
||||
|
||||
### 2.3 swagger注解的使用和说明
|
||||
|
||||
```java
|
||||
@Slf4j
|
||||
@Api(value = "产品接口", description = "产品信息接口")
|
||||
@RestController
|
||||
public class ProductController {
|
||||
|
||||
/***
|
||||
* 一个标准的swagger注解
|
||||
*/
|
||||
@ApiOperation(notes = "查询所有产品", value = "产品查询接口")
|
||||
@ApiImplicitParams(
|
||||
@ApiImplicitParam(name = "id", value = "产品编号", paramType = "path", defaultValue = "1")
|
||||
)
|
||||
@ApiResponses(value = {
|
||||
@ApiResponse(code = 200, message = "请求成功"),
|
||||
@ApiResponse(code = 400, message = "无效的请求"),
|
||||
@ApiResponse(code = 401, message = "未经过授权认证"),
|
||||
@ApiResponse(code = 403, message = "已经过授权认证，但是没有该资源对应的访问权限"),
|
||||
@ApiResponse(code = 404, message = "服务器找不到给定的资源,商品不存在"),
|
||||
@ApiResponse(code = 500, message = "服务器错误")
|
||||
})
|
||||
@GetMapping(value = "/product/{id}", produces = "application/json")
|
||||
public ResponseEntity<Product> getProduct(@PathVariable long id) {
|
||||
Product product = new Product(id, "product" + id, new Date());
|
||||
return ResponseEntity.ok(product);
|
||||
}
|
||||
|
||||
|
||||
/***
|
||||
* 如果用实体类接收参数,则用实体类对应的属性名称指定参数
|
||||
*/
|
||||
@ApiOperation(notes = "保存产品", value = "产品保存接口")
|
||||
@ApiImplicitParams({
|
||||
@ApiImplicitParam(name = "id", value = "产品编号", paramType = "body", defaultValue = "1"),
|
||||
@ApiImplicitParam(name = "name", value = "产品名称", paramType = "body"),
|
||||
@ApiImplicitParam(name = "date", value = "产品生产日期", paramType = "body")
|
||||
}
|
||||
)
|
||||
@PostMapping(value = "/product")
|
||||
public ResponseEntity<Void> saveProduct(@RequestBody Product product) {
|
||||
System.out.println(product);
|
||||
return ResponseEntity.ok().build();
|
||||
}
|
||||
|
||||
|
||||
/***
|
||||
* 在配置类中指明了该接口不被扫描到,可以在配置类中使用正则指定某一类符合规则的接口不被扫描到
|
||||
*/
|
||||
@ApiOperation(notes = "该接口会被忽略", value = "产品保存接口")
|
||||
@PostMapping(value = "/ignore")
|
||||
public ResponseEntity<Product> ignore() {
|
||||
return ResponseEntity.ok().build();
|
||||
}
|
||||
|
||||
/**
|
||||
* 不加上任何swagger相关的注解也会被扫描到 如果不希望被扫描到，需要用 @ApiIgnore 修饰
|
||||
*/
|
||||
@PostMapping(value = "/normal")
|
||||
public ResponseEntity<Void> normal() {
|
||||
return ResponseEntity.ok().build();
|
||||
}
|
||||
|
||||
@ApiIgnore
|
||||
@PostMapping(value = "/apiIgnore")
|
||||
public ResponseEntity<Void> apiIgnore() {
|
||||
return ResponseEntity.ok().build();
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
swagger 为了最大程度防止对逻辑代码的侵入，基本都是依靠注解来完成文档描述。常用注解如下：
|
||||
|
||||
| Annotation | Attribute | Target Property | Description |
|
||||
| ---------------- | ------------ | ------------------------- | ------------------------------------------------------------ |
|
||||
| RequestHeader | defaultValue | Parameter#defaultValue | e.g. `@RequestHeader(defaultValue="${param1.defaultValue}")` |
|
||||
| ApiModelProperty | value | ModelProperty#description | e.g. `@ApiModelProperty(value="${property1.description}")` |
|
||||
| ApiModelProperty | description | ModelProperty#description | e.g. `@ApiModelProperty(notes="${property1.description}")` |
|
||||
| ApiParam | value | Parameter#description | e.g. `@ApiParam(value="${param1.description}")` |
|
||||
| ApiImplicitParam | value | Parameter#description | e.g. `@ApiImplicitParam(value="${param1.description}")` |
|
||||
| ApiOperation | notes | Operation#notes | e.g. `@ApiOperation(notes="${operation1.description}")` |
|
||||
| ApiOperation | summary | Operation#summary | e.g. `@ApiOperation(value="${operation1.summary}")` |
|
||||
| RequestParam | defaultValue | Parameter#defaultValue | e.g. `@RequestParam(defaultValue="${param1.defaultValue}")` |
|
||||
|
||||
1. `@Api`：Api 用在类上，说明该类的作用；
|
||||
|
||||
2. `@ApiOperation`：用在方法上，说明方法的作用；
|
||||
|
||||
3. `@ApiParam`：用在参数上，说明参数的作用；
|
||||
|
||||
4. `@ApiImplicitParams`：用在方法上说明方法参数的作用；
|
||||
|
||||
5. `@ApiImplicitParam`：用在@ApiImplicitParams注解中，描述每个具体参数；
|
||||
|
||||
6. `@ApiResponses`：一组@ApiResponse的配置；
|
||||
|
||||
7. `@ApiResponse`：请求返回的配置；
|
||||
|
||||
8. `@ResponseHeader`：响应头的配置；
|
||||
|
||||
9. `@ApiModel`：描述一个Model的信息（一般用在post创建的时候，使用@RequestBody接收参数的场景）；
|
||||
|
||||
10. `@ApiModelProperty`：描述model的属性。
|
||||
|
||||
11. `@ApiIgnore`：可以用于类、方法、属性，代表该方法、类、属性不被swagger的文档所管理。
|
||||
|
||||
|
||||
|
||||
### 2.4 swagger-ui 可视化接口文档
|
||||
|
||||
接口文档访问地址：http://localhost:8080/swagger-ui.html#/，文档主界面如下：
|
||||
|
||||
<div align="center"> <img src="https://github.com/heibaiying/spring-samples-for-all/blob/master/pictures/swagger-ui-index.png"/> </div>
|
||||
|
||||
### 2.5 利用swagger-ui进行接口测试
|
||||
|
||||
|
||||
点击对应接口的`try it out`按钮可以进行接口测试，此时可以输入对应的参数的值，然后点击下方的`Execute`按钮发送请求。<div align="center"> <img src="https://github.com/heibaiying/spring-samples-for-all/blob/master/pictures/swagger-try-it.png"/> </div>
|
||||
|
||||
<div align="center"> <img src="https://github.com/heibaiying/spring-samples-for-all/blob/master/pictures/swagger-execute.png"/> </div>
|
||||
|
||||
post方法可以直接修改model 对应的 json数据 ，然后点击下方的`Execute`按钮发送请求。
|
||||
|
||||
<div align="center"> <img src="https://github.com/heibaiying/spring-samples-for-all/blob/master/pictures/swagger-post-try.png"/> </div>
|
||||
@ -1 +1,2 @@
|
||||
#swagger启用开关
|
||||
swagger.enable = true
|
||||
140
z-utils/GenNavigation.java
Normal file
140
z-utils/GenNavigation.java
Normal file
@ -0,0 +1,140 @@
|
||||
import javafx.util.Pair;
|
||||
|
||||
import java.io.File;
|
||||
import java.io.FileReader;
|
||||
import java.io.FileWriter;
|
||||
import java.io.IOException;
|
||||
import java.util.ArrayList;
|
||||
import java.util.List;
|
||||
import java.util.regex.Matcher;
|
||||
import java.util.regex.Pattern;
|
||||
|
||||
/**
|
||||
* @author : heibaiying
|
||||
* @description : 用于生成README.md导航目录的工具类
|
||||
*/
|
||||
public class GenNavigation {
|
||||
|
||||
public static void main(String[] args) {
|
||||
|
||||
if (args.length < 1) {
|
||||
System.out.println("请传递路径");
|
||||
return;
|
||||
}
|
||||
|
||||
String dir = args[0];
|
||||
|
||||
List<String> filesList = getAllFile(dir, new ArrayList<>());
|
||||
for (String filePath : filesList) {
|
||||
// 获取文件内容
|
||||
String content = getContent(filePath);
|
||||
// 获取全部标题
|
||||
List<Pair<String, String>> allTitle = getAllTitle(content);
|
||||
// 生成导航
|
||||
String nav = genNav(allTitle);
|
||||
// 写出并覆盖原文件
|
||||
write(filePath, content, nav);
|
||||
}
|
||||
System.out.println("生成目录成功！");
|
||||
}
|
||||
|
||||
private static void write(String filePath, String content, String nav) {
|
||||
try {
|
||||
String newContent = "";
|
||||
if (content.contains("## 目录") && content.contains("## 正文<br/>")) {
|
||||
// 如果原来有目录则替换
|
||||
newContent = content.replaceAll("(?m)(## 目录[\\s\\S]*## 正文<br/>)", nav);
|
||||
} else {
|
||||
StringBuilder stringBuilder = new StringBuilder(content);
|
||||
// 如果原来没有目录，则title和正文一个标题间写入
|
||||
int index = content.indexOf("## ");
|
||||
stringBuilder.insert(index - 1, nav);
|
||||
newContent = stringBuilder.toString();
|
||||
}
|
||||
// 写出覆盖文件
|
||||
FileWriter fileWriter = new FileWriter(new File(filePath));
|
||||
fileWriter.write(newContent);
|
||||
fileWriter.flush();
|
||||
} catch (IOException e) {
|
||||
e.printStackTrace();
|
||||
}
|
||||
|
||||
}
|
||||
|
||||
private static String genNav(List<Pair<String, String>> flagAndTitles) {
|
||||
StringBuilder builder = new StringBuilder();
|
||||
// 目录头
|
||||
builder.append("## 目录<br/>\n");
|
||||
for (Pair<String, String> ft : flagAndTitles) {
|
||||
String flag = ft.getKey();
|
||||
String title = ft.getValue();
|
||||
builder.append(genBlank(flag.length() - 2, 4));
|
||||
// Github有效目录格式: <a href="#21-预备">页面锚点</a> url中不能出现特殊符号
|
||||
String formatTitle = title.trim().replaceAll("[.():：（）|、,，@。]", "").replace(" ", "-");
|
||||
builder.append(String.format("<a href=\"%s\">%s</a><br/>\n", "#" + formatTitle, title));
|
||||
}
|
||||
// 目录尾
|
||||
builder.append("## 正文<br/>\n");
|
||||
return builder.toString();
|
||||
}
|
||||
|
||||
private static String genBlank(int i, int scale) {
|
||||
StringBuilder builder = new StringBuilder();
|
||||
for (int j = 0; j < i; j++) {
|
||||
for (int k = 0; k < scale; k++) {
|
||||
builder.append(" ");
|
||||
}
|
||||
}
|
||||
return builder.toString();
|
||||
}
|
||||
|
||||
private static List<Pair<String, String>> getAllTitle(String content) {
|
||||
List<Pair<String, String>> list = new ArrayList<>();
|
||||
Pattern pattern = Pattern.compile("(?m)^(#{2,10})\\s?(.*)");
|
||||
Matcher matcher = pattern.matcher(content);
|
||||
while (matcher.find()) {
|
||||
String group2 = matcher.group(2);
|
||||
if (!group2.contains("目录") && !group2.contains("正文")) {
|
||||
list.add(new Pair<>(matcher.group(1), group2));
|
||||
}
|
||||
}
|
||||
return list;
|
||||
}
|
||||
|
||||
private static String getContent(String filePath) {
|
||||
StringBuilder builder = new StringBuilder();
|
||||
|
||||
try {
|
||||
FileReader reader = new FileReader(filePath);
|
||||
char[] chars = new char[1024 * 1024];
|
||||
|
||||
int read = 0;
|
||||
while ((read = reader.read(chars)) != -1) {
|
||||
builder.append(new String(chars, 0, read));
|
||||
}
|
||||
} catch (IOException e) {
|
||||
e.printStackTrace();
|
||||
}
|
||||
return builder.toString();
|
||||
}
|
||||
|
||||
private static List<String> getAllFile(String dir, List<String> filesList) {
|
||||
File file = new File(dir);
|
||||
//如果是文件 则不遍历
|
||||
if (file.isFile() && file.getName().endsWith(".md")) {
|
||||
filesList.add(file.getAbsolutePath());
|
||||
}
|
||||
//如果是文件夹 则遍历下面的所有文件
|
||||
File[] files = file.listFiles();
|
||||
if (files != null) {
|
||||
for (File f : files) {
|
||||
if (f.isDirectory() && !f.getName().startsWith(".")) {
|
||||
getAllFile(f.getAbsolutePath(), filesList);
|
||||
} else if (f.getName().endsWith(".md")) {
|
||||
filesList.add(f.getAbsolutePath());
|
||||
}
|
||||
}
|
||||
}
|
||||
return filesList;
|
||||
}
|
||||
}
|
||||
Loading…
x
Reference in New Issue
Block a user