前言

先說說背景吧。這次改造是公司的項目。之前我們使用的showdoc進行接口文檔管理的。說實話，效果不錯。但是，問題是時間長了之后，接口文檔會和實現(xiàn)脫節(jié)從而無法信任接口文檔。這個問題其實我知道，但是，可能是體會少吧。由于從理想的角度來說，希望先出接口文檔再進行編碼，所以就拒絕使用swagger這種嵌入在代碼里的接口文檔維護方式。現(xiàn)在想來，還是太過理想化了。其實，如果真的要先出文檔再編碼，也可以借助寫文檔的過程把空接口寫出來。另外，由于我想明白了怎么用git實現(xiàn)研發(fā)流程（http://www.itdecent.cn/p/1bf5b3c6f1c8
），和現(xiàn)有產線的沖突問題也就不存在了。
再說說，為什么是knife4j而不是單純的swagger2。這個決策，其實沒那么嚴謹。多數原因是機緣巧合吧。在前段時間，我折騰怎么管理springcloud的文檔的時候，想要在gateway一個地方看到所有接口的文檔，折騰的時候找到的knife4j(http://www.itdecent.cn/p/ce56e783d40f
) 。后來發(fā)現(xiàn)，這個框架也不是專門為了解決springcloud集成而誕生的，它是一個swagger的ui美化項目，核心還是swagger，改了改界面。那就用它吧。反正，配置也挺透明的，實在不行，改個依賴也就改回去了。

依賴

這里的依賴，和gateway的引入不一樣，沒有那么多注意事項。

<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>knife4j-spring-boot-starter</artifactId>
    <version>2.0.2</version>
</dependency>

如上即可，版本自己改成合適的就行了。我選了個最新的。

配置

配置大體上分為兩部分：

• 基本設置，以讓框架生效，這包括了knife4j和swagger兩部分。雖然是兩部分，這里一并配置就可以了，很簡單。
• 會話設置。如果應用系統(tǒng)是需要登錄才能訪問各個接口的話，那它訪問swagger的接口也是需要登錄的，很不方便，這里我們就想辦法去掉它。

基本配置

@Configuration
@EnableSwagger2
@EnableKnife4j
@Import(BeanValidatorPluginsConfiguration.class)
public class SwaggerConfiguration {
    @Bean
    public Docket defaultApi2() {
        Docket docket=new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                //分組名稱
                .groupName("默認版本API")
                .select()
                //這里指定Controller掃描包路徑
                .apis(RequestHandlerSelectors.basePackage("com.ym"))
                .paths(PathSelectors.any())
                .build();
        return docket;
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("資源統(tǒng)一管理平臺API")
                .description("資源統(tǒng)一管理平臺提供的所有API")
                .version("1.0")
                .build();
    }
}

上面就是我基本配置的全部代碼?？梢钥吹絛efaultApi2方法才是真正的注冊bean的方法。而這個bean最主要的其實就是配置了掃描的基礎包路徑，至于apiinfo，那是頁面顯示的東西，沒多少實際用途。另外，最主要的要看到上面的三個注解。@EnableSwagger2、@EnableKnife4j這兩個就不解釋了，看名字就知道。@Import(BeanValidatorPluginsConfiguration.class)最后這個，說實話，我沒查，也不知道是干什么的，反正能運行了，回頭再說吧。

會話配置

我這個系統(tǒng)的api是有session的，所有接口會驗證其攜帶的sessionToken。所以，需要對相關的接口進行排除。官方說明的有下面這些：

/swagger-resources:Swagger的分組接口
/v2/api-docs?group=groupName:Swagger的具體分組實例接口,返回該分組下所有接口相關的Swagger信息
/v2/api-docs-ext?group=groupName:該接口是SwaggerBootstrapUi提供的增強接口地址,如不使用UI增強,則可以忽略該接口
/doc.html:接口界面url

具體排除我就不寫了，各應用使用的方法不同，需要的代碼也不同。總之，排除之后，訪問/doc.html，就可以看到接口文檔了。它應該是掃描了所有的controller注解，生成的。所以，沒有特意寫過的接口也可看到。

文檔配置

文檔配置的內容說來也很簡單。在類上標注ApiModel，在屬性上標注ApiModelProperty。這兩個注解可以幫助你控制在文檔中展示的內容。主要就是寫value。我還用到了required屬性。其它的，有需要的時候再研究吧。下面給兩個樣例吧：

@ApiModel(value="創(chuàng)建KeyValue請求對象")

@ApiModelProperty(value = "排序號.數值越大越靠前。取值范圍1~1000")