1 简单介绍
Swagger是一个实现了OpenAPI(OpenAPI
Specification)规范的工具集。OpenAPI是Linux基金会的一个项目，试图通过定义一种用来描述API格式或API定义的语言，来规范RESTful服务开发过程。
swagger大大方便了前后端开发人员，用过的人都说好。但是也有一些人并未体验过swagger，还在苦苦的手写接口文档，麻烦又不规范；还有一些人虽然用过，但是只是朦朦胧胧，看别人怎么用直接就CV过来用了，使用的很碎片，不系统。我之前就是这个样子，只知道添加个依赖，启动项目后访问：localhost:8080/swagger-ui.html，就能看到生成的文档了，很是简单。
看官方的说明：
Swagger包含的工具集：
Swagger编辑器： Swagger Editor允许您在浏览器中编辑YAML中的OpenAPI规范并实时预览文档。
Swagger UI： Swagger UI是HTML，Javascript和CSS资产的集合，可以从符合OAS标准的API动态生成漂亮的文档。
**Swagger Codegen：**允许根据OpenAPI规范自动生成API客户端库（SDK生成），服务器存根和文档。
**Swagger Parser：**用于解析来自Java的OpenAPI定义的独立库
**Swagger Core：**与Java相关的库，用于创建，使用和使用OpenAPI定义
Swagger Inspector（免费）： API测试工具，可让您验证您的API并从现有API生成OpenAPI定义
SwaggerHub（免费和商业）： API设计和文档，为使用OpenAPI的团队构建。
2 入门案例
SpringBoot已经集成了Swagger，使用简单注解即可生成swagger的API文档。
2.1 引入依赖
<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.2 编写配置
@Configuration @EnableSwagger2 // Swagger的开关，表示已经启用Swagger public class SwaggerConfig { @Bean public Docket api() { Docket docket = new Docket(DocumentationType.SWAGGER_2) .host("localhost:8081")// 不配的话，默认当前项目端口 .apiInfo(apiInfo()) .pathMapping("/") .select() // 选择哪些路径和api会生成document .apis(RequestHandlerSelectors.any())// 对所有api进行监控 // .apis(RequestHandlerSelectors.basePackage("com.hanstrovsky.controller"))// 选择监控的package // .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))// 只监控有ApiOperation注解的接口 //不显示错误的接口地址 .paths(Predicates.not(PathSelectors.regex("/error.*")))//错误路径不监控 .paths(PathSelectors.regex("/.*"))// 对根下所有路径进行监控 .build(); return docket; } private ApiInfo apiInfo() { return new ApiInfoBuilder().title("XXXX项目接口文档") .contact(new Contact("Hanstrovsky", "www.hanstrovsky.com", "Hanstrovsky@gmail.com")) .description("这是用Swagger动态生成的接口文档") .termsOfServiceUrl("NO terms of service") .license("The Apache License, Version 2.0") .licenseUrl("http://www.apache.org/licenses/LICENSE-2.0.html") .version("1.0") .build(); } }
2.3 启动测试
启动服务，访问：http://localhost:8081/swagger-ui.html
就能看到swagger-ui为我们提供的API页面了：
可以看到我们编写的接口，任意点击一个，即可看到接口的详细信息：
可以看到详细的接口声明，包括：
请求方式：
请求路径
请求参数
响应等信息
点击右上角的try it out!还可以测试接口。
3 常用注解
刚才的文档说明中，是swagge-ui根据接口自动生成，不够详细。如果有需要，可以通过注解自定义接口声明。常用的注解包括：
/** @Api：修饰整个类，描述Controller的作用 @ApiOperation：描述一个类的一个方法，或者说一个接口 @ApiParam：单个参数描述 @ApiModel：用对象来接收参数 @ApiProperty：用对象接收参数时，描述对象的一个字段 @ApiResponse：HTTP响应其中1个描述 @ApiResponses：HTTP响应整体描述 @ApiIgnore：使用该注解忽略这个API @ApiError ：发生错误返回的信息 @ApiImplicitParam：一个请求参数 @ApiImplicitParams：多个请求参数 */
示例：
@PostMapping("/people") @ApiOperation(value = "保存人员信息") @ApiResponses({ @ApiResponse(code = 0, message = "保存成功"), @ApiResponse(code = 1, message = "保存失败") }) public FrontResult save( @ApiParam(value = "保存参数", example = "") @RequestBody People people) { people.setBirthday(Timestamp.valueOf(LocalDateTime.now())); return new FrontResult(FrontResult.SUCCEED, "保存成功", peopleDao.save(people)); } @Data @ApiModel(description = "人员信息保存请求对象") public class People { @ApiModelProperty(value = "人员编号") private Long id; @ApiModelProperty(value = "姓名", required = true,position = 1) private String name; @ApiModelProperty(value = "性别", required = true,position = 2) private String sex; @ApiModelProperty(value = "生日", required = true,position = 3) @JsonFormat(pattern = "yyyy-MM-dd HH:mm:ss") private Timestamp birthday; }
4 生成可以生成文档的增强
如果觉得用起来不太习惯，可以用Swagger-Bootstrap-UI 替换Swagger 默认的UI实现左右菜单风格的Swagger-UI ，让其看起来更清晰明了。
4.1 添加依赖
<!-- https://mvnrepository.com/artifact/com.github.xiaoymin/swagger-bootstrap-ui --> <dependency> <groupId>com.github.xiaoymin</groupId> <artifactId>swagger-bootstrap-ui</artifactId> <version>1.9.6</version> </dependency>
4.2 重启项目
访问 http://localhost:8080/doc.html ：
之后可以下载离线文档
5 记录生产环境的坑
交给运维部然后给我配置文件加了一个访问路径的前缀,我说怎么访问都是404
rest风格的话get请求是不能带requestbody,因为他会拼接到url上
6 生成docx文档
采用方式为md转docx
md文件转word需要安装插件pandoc:https://github.com/jgm/pandoc/releases/
6.1 pandoc安装
可以直接下载.msi程序版本无所谓
直接点击安装，一直Next即可
安装完成之后需要配置环境变量
6.2 文件转换
如果是已经写好的md文档，则可以使用命令来转换文件
pandoc -s 文件名.md -o 文件名.docx
6.3 遇到的问题
导出的word文档中，图片丢失
可能原因：
图片路径
文档路径
解决办法：
将md文档中的图片链接都替换成相对路径，如
直接在当前目录下进行转换（我在转换之前将文件拷贝到其他地方导致转换后图片丢失）
