SwaggerUI 笔记
**
由已有的经swagger2注解过的代码,自动生成swaggerUI文档,并将文档转成Word形式保存。
**
- 引入swagger2依赖
```java
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.8.0</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.8.0</version>
</dependency>
- 代码中使用swagger2注解
@RestController
@RequestMapping("/br/readerBook")
@Api(value = "借还管理",description = "借还管理")
public class ReaderBookController {
@Autowired
private ReaderBookServiceImpl readerBookService;
@Autowired
private ReadersServiceImpl readersService;
@Autowired
private BooksServiceImpl booksService;
@ApiOperation("查询所有借阅记录")
@RequestMapping(value = "/", method = RequestMethod.GET)
public Result findAll() {
List<Map<String, String>> page = readerBookService.getlist();
if (page == null) {
return new Result(false, 50008, "获取失败");
}
return new Result(true, 20000, "获取成功", page);
}
- 配置使swagger生效及配置swagger其他信息
@Configuration
@EnableSwagger2
public class MyConfiguration {
/**
* 创建API应用
* apiInfo() 增加API相关信息
* 通过select()函数返回一个ApiSelectorBuilder实例,用来控制哪些接口暴露给Swagger来展现,
* 本例采用指定扫描的包路径来定义指定要建立API的目录。
*访问地址:http://项目实际地址/swagger-ui.html
* 访问地址:http://localhost:80/mylib/swagger-ui.html
* @return
*/
public Docket createRestApi() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
//Controller所在包(必须新建包)
.apis(RequestHandlerSelectors.basePackage("com.hust.mylib"))
.paths(PathSelectors.any())
.build();
}
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
//接口文档的名字
.title("图书信息管理系统")
//接口文档的描述
.description("图书信息管理系统 api接口文档")
//服务条款网址
.termsOfServiceUrl("http://localhost/")
//接口文档的版本
.version("1.0.0")
// 接口文档维护联系信息
.contact(new Contact("ABC", "", "********@qq.com"))
.build();
}
}
4.启动项目后,访问 http://localhost:80/mylib/swagger-ui.html
(备注:项目服务器地址为localhost,端口为:80,其中设置项目上下文路径为“ /mylib”)
踩坑提示:访问路径 http://localhost:80/mylib/swagger-ui.html需要添加项目上下文路径,而非http://localhost:80/swagger-ui.html,即使设置中是.termsOfServiceUrl("http://localhost/")
5.进入到Swagger-UI页面
6.下一步,将该页面转成Word格式文档。点击“http://localhost/mylib/v2/api-docs”得到JSON字符串。
7.复制该JSON字符串,写入文本,存成 **.json文件。
排雷提示:将文件存成以UTF-8编码的文件,否则后面生成的Word可能会乱码。
8.下面用一个工程,将json 解析并渲染生成漂亮的Word格式文档。
工程地址:https://github.com/JMCuixy/swagger2word.git。
9.启动工程,访问地址: http://127.0.0.1:8080/swagger-ui.html
10.点击
11.按图示步骤进行下去得到Word文档。
12.得到Word文档。
(若JSON未保存成UTF-8编码,此处的文档可能乱码。)
大功告成!
备注:
此外,可以不使用JSON文档进行转化,用更简便的方法:直接将http://localhost:80/swagger-ui.html网址提供给转Word项目工程亦可,如下图所示:
但我没成功,所以采用的比较麻烦的方法。
详见swagger2word项目中的说明文档。
https://github.com/JMCuixy/swagger2word#%E4%BD%BF%E7%94%A8%E6%AD%A5%E9%AA%A4google-chrome
特别感谢GitHub作者JMCuixy,新手不知如何引用,点星致意。
新手上路,理解不到位请指正。