SpringBoot&Swagger构建REST API并生成API文档
一、理论基础
Swagger是什么？？
背景：
现在的网站架构基本都由原来的后端渲染，
变成了：前端渲染、先后端分离的形态.
前后端交互的方式：api接口
api文档是提升开发效率
而swagger就是一款让你更好的书写API文档的框架。
没有swagger之前文档都是手写api,有写在confluence上，也有在readme里的。文档书写工具加多，而swagger拥有更好的支持。
特点
功能丰富 ：支持多种注解，自动生成接口文档界面，支持在界面测试API接口功能；
及时更新 ：开发过程中花一点写注释的时间，就可以及时的更新API文档，省心省力；
整合简单 ：通过添加pom依赖和简单配置，内嵌于应用中就可同时发布API接口文档界面，不需要部署独立服务。同类型产品：轻量级rap 开发者阿里巴巴rap的github地址
二、swagger生态使用图
这部分可以快速了解下
简单描述下红颜色的是swaggger官网方推荐的。
1.swagger-ui
用来显示API文档的。添加ui的pom就可以获得一个简单的视图
点一个controller进去能够看到具体方法
2.swagger-editor
就是一个在线编辑文档说明文件（swagger.json或swagger.yaml文件）的工具，以方便生态中的其他小工具（swagger-ui）等使用。
在编辑器，左边编辑，右边立马就显示出编辑自己想要的效果出来。
编辑swagger说明文件使用的是yaml语法格式。具体的使用可以在官网查看https://swagger.io/。
补充：各种语言版本的根据annotation或者注释生成swagger说明文档的工具，也就是说它扩语言。
目前最流行的做法，就是在代码注释中写上swagger相关的注释，然后，利用小工具生成swagger.json或者swagger.yaml文件。
3.swagger-validator
这个小工具是用来校验生成的文档说明文件是否符合语法规定的。用法非常简单，只需url地址栏，根路径下加上一个参数url，参数内容是放swagger说明文件的地址。即可校验。
docker hub地址为：https://hub.docker.com/r/swaggerapi/swagger-validator/
4.swagger-codegen
代码生成器，脚手架。
作用：可以根据swagger.json或者swagger.yml文件生成指定的计算机语言指定框架的代码。
5.mock server
这个目前还没有找到很合适的mock工具，包括rap也好，其他API文档工具也好，都做的不够完善，大多就是根据说明文件，例如swagger.json等生成一些死的静态的mock数据，不能够根据限定条件：例如“只能是数字，必传”等做出合理的回应。
简单来说就是支持的不够完善。
三、与SpringBoot整合
第一步、添加pom依赖
需要添加的依赖为swagger2核心包和swagger-ui(方便使用自带的ui界面)包
这里使用2.7.0版本为例
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.7.0</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.7.0</version>
</dependency>第二步、将swagger-ui中的界面配置至spring-boot配置文件中。
因为spring-boot有自己的一套web端拦截机制，若需要看到swagger发布的api文档界面，需要做一些特殊的配置，可以将springfox-swagger-ui包中的ui界面暴露给spring-boot资源环境。
@Configuration
public class WebMvcConfig extends WebMvcConfigurerAdapter {
@Override
public void addResourceHandlers(ResourceHandlerRegistry registry) {
registry.addResourceHandler("/js/**").addResourceLocations("classpath:/js/");
registry.addResourceHandler("swagger-ui.html")
.addResourceLocations("classpath:/META-INF/resources/");
registry.addResourceHandler("/webjars/**")
.addResourceLocations("classpath:/META-INF/resources/webjars/");
}
}第三步、配置API文档页基本信息
spring-boot 和 swagger 整合时，使用注解注入相关配置。
通过这些配置可以指定在spring-boot启动时扫描哪些controller层的文件夹，
另外可以指定API文档页的标题和描述信息等内容。
@Configuration
@EnableSwagger2
public class Swagger2 {
@Bean
public Docket createRestApi() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
.apis(RequestHandlerSelectors.basePackage("com.xx.web.controller"))
.paths(PathSelectors.any())
.build();
}
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("xx项目 RESTful APIs")
.description("xx项目后台api接口文档")
.version("1.0")
.build();
}
}第四步、API文档编写示例
我们一般会在Controller层，将详尽的API接口输入输出在代码中通过注解进行相关描述，下面给出一个接口描写示例，具体的写法可以参考其api文档的具体说明：
@Api(value = "PageController", description = "用户登录登出接口")
@Controller
@RequestMapping("/")
public class PageController {
@ApiOperation(value="用户登录", notes="用户登录接口")
@ApiImplicitParams({
@ApiImplicitParam(name = "username", value = "用户名", required = true ,dataType = "string"),
@ApiImplicitParam(name = "passwd", value = "密码", required = true ,dataType = "string")
})
@RequestMapping(value = "/login",method = {RequestMethod.POST,RequestMethod.GET})
@ResponseBody
public ModelMap login(Users data, HttpServletRequest request){
//ToDo
}
}第五步、通过ui界面，在线查看及测试API文档
访问localhost:8080/swagger-ui.html
找到一个方法点进去
到这一步一个简单的demo也就完成
一个现成可以直接下载并运行的demo
git clone https://github.com/tianxuxu/de.git四、如何将在线文档离线
整理一下生成离线文档的思路
首先给controller添加注解生成api
将路径”/v2/api-docs”下的文件生成.json文件
将.json文件生成中间文件.adoc文件
将.adoc文件合成自己想要的pdf文件或者html或者doc文件
这里其实我也不太明白
步骤大致就是额外需要的pom
添加文件格式转化所需swagger2markup和相关静态文件所需的包
<dependency>
<groupId>org.springframework.restdocs</groupId>
<artifactId>spring-restdocs-mockmvc</artifactId>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-staticdocs</artifactId>
<version>2.6.1</version>
</dependency>
<dependency>
<groupId>io.github.robwin</groupId>
<artifactId>assertj-swagger</artifactId>
<version>0.2.0</version>
<scope>test</scope>
</dependency>
<dependency>
<groupId>io.github.swagger2markup</groupId>
<artifactId>swagger2markup-spring-restdocs-ext</artifactId>
<version>1.2.0</version>
<scope>test</scope>
</dependency>另外还需要在pom文件配置静态文件的生成目录啥的完整的pom参考后面附带的github项目这里的pom
我也不太明白为啥网上所有的例子都是都是通过运行mvn test生成文件的
只能附上test中的生成.json代码
@RunWith(SpringJUnit4ClassRunner.class)
@SpringBootTest(classes = {SpringFoxSwagger2MarkupApplication.class, SwaggerConfig.class})
@AutoConfigureMockMvc
@WebAppConfiguration
public class Swagger2MarkupTests {
private static final Logger LOG = LoggerFactory.getLogger(Swagger2MarkupTests.class);
@Autowired
private MockMvc mockMvc;
@Test
public void createSpringFoxSwaggerJson() throws Exception {
//String designFirstSwaggerLocation = Swagger2MarkupTest.class.getResource("/swagger.yaml").getPath();
String outputDir = System.getProperty("io.springfox.staticdocs.outputDir"); // mvn test
// String outputDir = "D:\\workspace\\springfox-swagger2-demo\\target\\swagger"; // run as
LOG.info("--------------------outputDir: {}--------------------", outputDir);
MvcResult mvcResult = this.mockMvc.perform(get("/v2/api-docs")
.accept(MediaType.APPLICATION_JSON))
.andExpect(status().isOk())
.andReturn();
MockHttpServletResponse response = mvcResult.getResponse();
String swaggerJson = response.getContentAsString();
Files.createDirectories(Paths.get(outputDir));
try (BufferedWriter writer = Files.newBufferedWriter(Paths.get(outputDir, "swagger.json"), StandardCharsets.UTF_8)){
writer.write(swaggerJson);
}
LOG.info("--------------------swaggerJson create --------------------");
}
}
因为整合SpringBoot熟悉了Swagger2的基本用法后那么再次查看Swagger2的实例就应该不再困难
这里附上一个swagger2的生成离线pdf/html的例子
这是别人写的一个例子，我忘记从哪找的了，但是我把它传到了github
这里可以下载
git clone https://github.com/tianxuxu/springfox_swagger2markup.git导入项目完成后，执行mvn test
就可以看到它在pom中指定的目录完成静态文档的生成
这篇只能算是个入门的文章，可以快速了解下swagger2,对具体的api了解和使用还是要查看官方网站https://swagger.io/。