最近的一個(gè)新項(xiàng)目，在定義后端接口的時(shí)候，發(fā)現(xiàn)有些字段和接口名需要頻繁的更改。以前的實(shí)現(xiàn)方式是定義一個(gè)wiki，通過(guò)wiki來(lái)描述接口，但是隨著時(shí)間的流逝已經(jīng)各種小的變更，wiki和實(shí)際的接口實(shí)現(xiàn)差別越來(lái)越大?；镜搅艘环N不可維護(hù)的狀態(tài)。
前一段時(shí)間在翻github的時(shí)候，正好看到swagger項(xiàng)目。搜索了一下，發(fā)現(xiàn)確實(shí)很不錯(cuò)，能很好的描述接口，遂決定在新項(xiàng)目中使用一下。

注:本文是基于springboot配置實(shí)現(xiàn)，但在實(shí)際中使用springmvc和本文的配置基本一致，不影響使用。

下面是第一種配置方式。盡量精簡(jiǎn)的配置。
一
1 在pom文件中引入依賴(lài)

<!-- Swagger -->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.7.0</version>
</dependency>
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.7.0</version>
</dependency>

2 新建swag配置文件
在代碼中新定義一個(gè)類(lèi)，代碼如下

@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("對(duì)外開(kāi)放接口API 文檔")
                .description("HTTP對(duì)外開(kāi)放接口")
                .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";
    }
}

如上的配置就可以了，下面是展示效果
在本地啟動(dòng)項(xiàng)目，然后瀏覽器輸入：

http://localhost:8080/swagger-ui.html
效果如下：

swagger.png

這種配置方式非常簡(jiǎn)單，對(duì)原有的代碼也基本沒(méi)有任何侵入性?；究梢詽M足接口描述的需求。

但是，有很多項(xiàng)目都是前后端分離的，在nginx中會(huì)配置把 "/rest/" 開(kāi)頭的鏈接打到后端來(lái)，而把其他請(qǐng)求打到前端去。當(dāng)然，你可以修改nginx的配置，把某些鏈接打到前端去，剩下的直接打到后端。不過(guò)這種方式會(huì)有一定的安全性問(wèn)題，可控性也不太好。最好能給修改swagger的展示地址，
比如從
http://localhost:8080/swagger-ui.html
修改為
http://localhost:8080/rest/api/doc/swagger-ui.html

下面就是第二種配置方式，可以自定義展示鏈接。
二
1 在pom文件中引入依賴(lài)（注意我們?nèi)サ袅藢?duì)springfox-swagger-ui的依賴(lài)）

<!-- Swagger -->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.7.0</version>
</dependency>

2 git clone swagger-ui項(xiàng)目

https://github.com/swagger-api/swagger-ui
請(qǐng)選擇2.0以上,3.0以下版本

將其中的dist文件夾拷貝到自己項(xiàng)目中的resources/swagger目錄下，如圖

dist.png

3 在resources下新建swagger.properties文件，其中的內(nèi)容為

springfox.documentation.swagger.v2.path=/rest/api/doc

4 修改resources/swagger/dist 下的index文件
將其中的

  <script type="text/javascript">
    $(function () {
      var url = window.location.search.match(/url=([^&]+)/);
      if (url && url.length > 1) {
        url = decodeURIComponent(url[1]);
      } else {
        url = "http://petstore.swagger.io/v2/swagger.json";
      }

url = "http://petstore.swagger.io/v2/swagger.json"
修改為
url = "/rest/api/doc"
修改后如下

  <script type="text/javascript">
    $(function () {
      var url = window.location.search.match(/url=([^&]+)/);
      if (url && url.length > 1) {
        url = decodeURIComponent(url[1]);
      } else {
        url = "/rest/api/doc";
      }

5 新建swag配置文件
在代碼中新定義一個(gè)類(lèi)，代碼如下

@Configuration
@EnableSwagger2
@PropertySource("classpath:swagger.properties") // 新增對(duì)swagger.properties 的引入
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("對(duì)外開(kāi)放接口API 文檔")
                .description("HTTP對(duì)外開(kāi)放接口")
                .version("1.0.0")
                .termsOfServiceUrl("http://xxx.xxx.com")
                .license("LICENSE")
                .licenseUrl("http://xxx.xxx.com")
                .build();
    }
}

6 增加url映射
如果是springboot，在Application中增加

@SpringBootApplication
public class DemoApplication extends WebMvcConfigurerAdapter {
    @Override
    public void addResourceHandlers(ResourceHandlerRegistry registry) {
        registry.addResourceHandler("/rest/api/doc/**").addResourceLocations("classpath:/swagger/dist/");
    }
 .....
}

如果是springmvc，則在api-servlet.xml(application.xml)中增加

<mvc:resources mapping="/rest/api/doc/**" location="classpath:/swagger/dist/"/>

終于配置完成，啟動(dòng)項(xiàng)目，在瀏覽器中輸入：

http://localhost:8080/rest/api/doc/index.html

swagger.png

springfox官網(wǎng)

http://springfox.github.io/springfox/

api注解相關(guān)描述可參考

http://blog.csdn.net/xupeng874395012/article/details/68946676