最近的一个新项目，在定义后端接口的时候，发现有些字段和接口名需要频繁的更改。以前的实现方式是定义一个wiki，通过wiki来描述接口，但是随着时间的流逝已经各种小的变更，wiki和实际的接口实现差别越来越大。基本到了一种不可维护的状态。
前一段时间在翻github的时候，正好看到swagger项目。搜索了一下，发现确实很不错，能很好的描述接口，遂决定在新项目中使用一下。
注:本文是基于springboot配置实现，但在实际中使用springmvc和本文的配置基本一致，不影响使用。
下面是第一种配置方式。尽量精简的配置。
一
1 在pom文件中引入依赖
io.springfox
springfox-swagger-ui
2.7.0
io.springfox
springfox-swagger2
2.7.0
2 新建swag配置文件
在代码中新定义一个类，代码如下
@Configuration
@EnableSwagger2
public class SwaggerConfig {
@Bean
public Docket api() {
return new Docket(DocumentationType.SWAGGER_2)
.select()
.apis(RequestHandlerSelectors.any())
.build()
.apiInfo(apiInfo());
}
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("对外开放接口API 文档")
.description("HTTP对外开放接口")
.version("1.0.0")
.termsOfServiceUrl("http://xxx.xxx.com")
.license("LICENSE")
.licenseUrl("http://xxx.xxx.com")
.build();
}
}
3 在自己的controller中使用
@Slf4j
@RestController
public class MyController {
@RequestMapping(value = "hello", method = RequestMethod.GET)
public String hello() {
return "hello";
}
}
如上的配置就可以了，下面是展示效果
在本地启动项目，然后浏览器输入：
http://localhost:8080/swagger-ui.html
效果如下：
swagger.png
这种配置方式非常简单，对原有的代码也基本没有任何侵入性。基本可以满足接口描述的需求。
但是，有很多项目都是前后端分离的，在nginx中会配置把 "/rest/" 开头的链接打到后端来，而把其他请求打到前端去。当然，你可以修改nginx的配置，把某些链接打到前端去，剩下的直接打到后端。不过这种方式会有一定的安全性问题，可控性也不太好。最好能给修改swagger的展示地址，
比如从
http://localhost:8080/swagger-ui.html
修改为
http://localhost:8080/rest/api/doc/swagger-ui.html
下面就是第二种配置方式，可以自定义展示链接。
二
1 在pom文件中引入依赖（注意我们去掉了对springfox-swagger-ui的依赖）
io.springfox
springfox-swagger2
2.7.0
2 git clone swagger-ui项目
https://github.com/swagger-api/swagger-ui
请选择2.0以上,3.0以下版本
将其中的dist文件夹拷贝到自己项目中的resources/swagger目录下，如图
3 在resources下新建swagger.properties文件，其中的内容为
springfox.documentation.swagger.v2.path=/rest/api/doc
4 修改resources/swagger/dist 下的index文件
将其中的