diff --git a/README.md b/README.md index 2eb4209..bfa6828 100644 --- a/README.md +++ b/README.md @@ -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/) |
diff --git a/pictures/Swagger_UI.png b/pictures/Swagger_UI.png new file mode 100644 index 0000000..01f86c3 Binary files /dev/null and b/pictures/Swagger_UI.png differ diff --git a/pictures/swagger-execute.png b/pictures/swagger-execute.png new file mode 100644 index 0000000..76819ee Binary files /dev/null and b/pictures/swagger-execute.png differ diff --git a/pictures/swagger-post-try.png b/pictures/swagger-post-try.png new file mode 100644 index 0000000..8e8a6c8 Binary files /dev/null and b/pictures/swagger-post-try.png differ diff --git a/pictures/swagger-try-it.png b/pictures/swagger-try-it.png new file mode 100644 index 0000000..6b2fcd6 Binary files /dev/null and b/pictures/swagger-try-it.png differ diff --git a/pictures/swagger-ui-index.png b/pictures/swagger-ui-index.png new file mode 100644 index 0000000..e91a4ca Binary files /dev/null and b/pictures/swagger-ui-index.png differ diff --git a/pictures/swagger-ui-response.png b/pictures/swagger-ui-response.png new file mode 100644 index 0000000..7f7c86c Binary files /dev/null and b/pictures/swagger-ui-response.png differ diff --git a/spring-boot/spring-boot-swagger2/README.md b/spring-boot/spring-boot-swagger2/README.md new file mode 100644 index 0000000..39c8988 --- /dev/null +++ b/spring-boot/spring-boot-swagger2/README.md @@ -0,0 +1,266 @@ +# spring boot 整合 swagger 2.0 + ## 目录
+一、Springfox 与 Swagger 简介
+    1.1 Springfox
+    1.2 Swagger
+    1.3 OpenApi、Swagger、Springfox的关系
+二、spring boot 集成 swagger 2.0
+    2.1 导入项目相关依赖
+    2.2 进行swagger个性化配置、并用@EnableSwagger2开启Swagger支持
+    2.3 swagger注解的使用和说明
+    2.4 swagger-ui 可视化接口文档
+    2.5 利用swagger-ui进行接口测试
+## 正文
+ +## 一、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 提供的文档可视化界面示例： + +
+ + + +### 1.3 OpenApi、Swagger、Springfox的关系 + +**Swagger Core 是 OpenApi 规范（以前称为Swagger规范）的Java 实现，而 Springfox 提供 Swagger 与 spring 的集成支持**。 + + + +## 二、spring boot 集成 swagger 2.0 + +### 2.1 导入项目相关依赖 + +```xml + + + io.springfox + springfox-swagger2 + 2.9.2 + + + + io.springfox + springfox-swagger-ui + 2.9.2 + +``` + + + +### 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 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 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 saveProduct(@RequestBody Product product) { + System.out.println(product); + return ResponseEntity.ok().build(); + } + + + /*** + * 在配置类中指明了该接口不被扫描到,可以在配置类中使用正则指定某一类符合规则的接口不被扫描到 + */ + @ApiOperation(notes = "该接口会被忽略", value = "产品保存接口") + @PostMapping(value = "/ignore") + public ResponseEntity ignore() { + return ResponseEntity.ok().build(); + } + + /** + * 不加上任何swagger相关的注解也会被扫描到 如果不希望被扫描到，需要用 @ApiIgnore 修饰 + */ + @PostMapping(value = "/normal") + public ResponseEntity normal() { + return ResponseEntity.ok().build(); + } + + @ApiIgnore + @PostMapping(value = "/apiIgnore") + public ResponseEntity 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#/，文档主界面如下： + +
+ +### 2.5 利用swagger-ui进行接口测试 + + +​点击对应接口的`try it out`按钮可以进行接口测试，此时可以输入对应的参数的值，然后点击下方的`Execute`按钮发送请求。
+ +
+ +post方法可以直接修改model 对应的 json数据 ，然后点击下方的`Execute`按钮发送请求。 + +
\ No newline at end of file diff --git a/spring-boot/spring-boot-swagger2/src/main/resources/application.properties b/spring-boot/spring-boot-swagger2/src/main/resources/application.properties index 2c3050a..abaa428 100644 --- a/spring-boot/spring-boot-swagger2/src/main/resources/application.properties +++ b/spring-boot/spring-boot-swagger2/src/main/resources/application.properties @@ -1 +1,2 @@ +#swaggerÿ swagger.enable = true \ No newline at end of file diff --git a/z-utils/GenNavigation.java b/z-utils/GenNavigation.java new file mode 100644 index 0000000..1849a6e --- /dev/null +++ b/z-utils/GenNavigation.java @@ -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 filesList = getAllFile(dir, new ArrayList<>()); + for (String filePath : filesList) { + // 获取文件内容 + String content = getContent(filePath); + // 获取全部标题 + List> 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("## 正文
")) { + // 如果原来有目录则替换 + newContent = content.replaceAll("(?m)(## 目录[\\s\\S]*## 正文
)", 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> flagAndTitles) { + StringBuilder builder = new StringBuilder(); + // 目录头 + builder.append("## 目录
\n"); + for (Pair ft : flagAndTitles) { + String flag = ft.getKey(); + String title = ft.getValue(); + builder.append(genBlank(flag.length() - 2, 4)); + // Github有效目录格式: 页面锚点 url中不能出现特殊符号 + String formatTitle = title.trim().replaceAll("[.():：（）|、,，@。]", "").replace(" ", "-"); + builder.append(String.format("%s
\n", "#" + formatTitle, title)); + } + // 目录尾 + builder.append("## 正文
\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> getAllTitle(String content) { + List> 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 getAllFile(String dir, List 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; + } +}