參考：
https://doc.xiaominfo.com/guide/useful.html
UI特點
- 以markdown形式展示文檔,將文檔的請求地址、類型、請求參數、示例、響應參數分層次依次展示,接口文檔一目瞭然,方便開發者對接
- 在線調試欄除了自動解析參數外,針對必填項着顏色區分,同時支持tab鍵快速輸入上下切換.調試時可自定義Content-Type請求頭類型
- 個性化配置項,支持接口地址、接口description屬性、UI增強等個性化配置功能
- 接口排序,支持分組及接口的排序功能
- 支持markdown文檔離線文檔導出,也可在線查看離線文檔
- 調試信息全局緩存,頁面刷新後依然存在,方便開發者調試
- 以更人性化的treetable組件展示Swagger Models功能
- 響應內容可全屏查看,針對響應內容很多的情況下，全屏查看，方便調試、複製
- 文檔以多tab方式可顯示多個接口文檔
- 請求參數欄請求類型、是否必填着顏色區分
- 主頁中粗略統計接口不同類型數量
- 支持接口在線搜索功能
- 左右菜單和內容頁可自由拖動寬度
- 支持自定義全局參數功能，主頁包括header及query兩種類型
- i18n國際化支持,目前支持：中文簡體、中文繁體、英文
- JSR-303 annotations 註解的支持
快速開始
java開發
如果你是一名Java開發工程師,那麼使用swagger-bootstrap-ui將會非常簡單,只需要在原使用的基礎上,添加swagger-bootstrap-ui的maven引用jar包即可
Maven中引入Jar包
由於是springfox-swagger的增強UI包,所以基礎功能依然依賴Swagger,springfox-swagger的jar包必須引入
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.9.2</version>
</dependency>
然後引入SwaggerBootstrapUi的jar包
<dependency>
<groupId>com.github.xiaoymin</groupId>
<artifactId>swagger-bootstrap-ui</artifactId>
<version>${lastVersion}</version>
</dependency>
1.9.6
編寫Swagger2Config配置文件
Swagger2Config配置文件如下：
@Configuration
@EnableSwagger2
public class SwaggerConfiguration {
@Bean
public Docket createRestApi() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
.apis(RequestHandlerSelectors.basePackage("com.bycdao.cloud"))
.paths(PathSelectors.any())
.build();
}
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("swagger-bootstrap-ui RESTful APIs")
.description("swagger-bootstrap-ui")
.termsOfServiceUrl("http://localhost:8999/")
.contact("[email protected]")
.version("1.0")
.build();
}
}
訪問地址
swagger-bootstrap-ui默認訪問地址是：http://${host}:${port}/doc.html
注意事項
Springfox-swagger默認提供了兩個Swagger接口,需要開發者放開權限(如果使用shiro權限控制框架等)，如果使用SwaggerBootstrapUi的增強功能,還需放開增強接口地址,所以，放開的權限接口包括3個，分別是：
/swagger-resources:Swagger的分組接口/v2/api-docs?group=groupName:Swagger的具體分組實例接口,返回該分組下所有接口相關的Swagger信息/v2/api-docs-ext?group=groupName:該接口是SwaggerBootstrapUi提供的增強接口地址,如不使用UI增強,則可以忽略該接口
Shiro 的相關配置實例如下：
<!---other settings-->
<property name="filterChainDefinitions">
<value>
/swagger-resources = anon
/v2/api-docs = anon
/v2/api-docs-ext = anon
/doc.html = anon
/webjars/** = anon
//others....
</value>
</property>
SpringBoot 中訪問 doc.html 報404的解決辦法
實現SpringBoot的WebMvcConfigurer接口，添加相關的ResourceHandler,代碼如下：
@SpringBootApplication
@ConditionalOnClass(SpringfoxWebMvcConfiguration.class)
public class SwaggerBootstrapUiDemoApplication implements WebMvcConfigurer{
@Override
public void addResourceHandlers(ResourceHandlerRegistry registry) {
registry.addResourceHandler("doc.html").addResourceLocations("classpath:/META-INF/resources/");
registry.addResourceHandler("/webjars/**").addResourceLocations("classpath:/META-INF/resources/webjars/");
}
}
使用SpringMvc的朋友.在 web.xml 中配置了DispatcherServlet,則需要追加一個url匹配規則,如下（cmsMvc 爲 DispatcherServlet 的定義名）
<servlet>
<servlet-name>cmsMvc</servlet-name>
<servlet-class>org.springframework.web.servlet.DispatcherServlet</servlet-class>
<init-param>
<param-name>contextConfigLocation</param-name>
<param-value>classpath:config/spring.xml</param-value>
</init-param>
<load-on-startup>1</load-on-startup>
</servlet>
<!--默認配置,.htm|.do|.json等等配置-->
<servlet-mapping>
<servlet-name>cmsMvc</servlet-name>
<url-pattern>*.htm</url-pattern>
</servlet-mapping>
<!-- 配置swagger-bootstrap-ui的url請求路徑-->
<servlet-mapping>
<servlet-name>cmsMvc</servlet-name>
<url-pattern>/v2/api-docs</url-pattern>
</servlet-mapping>
<servlet-mapping>
<servlet-name>cmsMvc</servlet-name>
<url-pattern>/swagger-resources</url-pattern>
</servlet-mapping>
<servlet-mapping>
<servlet-name>cmsMvc</servlet-name>
<url-pattern>/v2/api-docs-ext</url-pattern>
</servlet-mapping>
更名knife4j
一開始項目初衷是爲了寫一個增強版本的Swagger 前端UI,但是隨着項目的發展,面對越來越多的個性化需求,不得不編寫後端Java代碼以滿足新的需求,在swagger-bootstrap-ui的1.8.5~1.9.6版本之間,採用的是後端Java代碼和Ui都混合在一個Jar包裏面的方式提供給開發者使用.這種方式雖說對於集成swagger來說很方便,只需要引入jar包即可,但是在微服務架構下顯得有些臃腫。
因此,項目正式更名爲knife4j,取名knife4j是希望她能像一把匕首一樣小巧,輕量,並且功能強悍,更名也是希望把她做成一個爲Swagger接口文檔服務的通用性解決方案,不僅僅只是專注於前端Ui前端.
swagger-bootstrap-ui的所有特性都會集中在knife4j-spring-ui包中,並且後續也會滿足開發者更多的個性化需求.
主要的變化是,項目的相關類包路徑更換爲com.github.xiaoymin.knife4j前綴,開發者使用增強註解時需要替換包路徑
後端Java代碼和ui包分離爲多個模塊的jar包,以面對在目前微服務架構下,更加方便的使用增強文檔註解(使用SpringCloud微服務項目,只需要在網關層集成UI的jar包即可,因此分離前後端)
knife4j沿用swagger-bootstrap-ui的版本號,第1個版本從1.9.6開始,關於使用方法,請參考文檔
knife4j目前的項目結構
|-knife4j
|-----knife4j-annotations // 提供的增強註解包
|-----knife4j-core // 相關業務邏輯核心包
|-----knife4j-spring //spring項目使用swagger是可以直接使用該jar包
|-----knife4j-spring-ui // swagger前端ui文檔,訪問方式不變,還是doc.html
|-----knife4j-spring-boot-starter //knife4j爲Spring Boot項目提供的starter組件
不同項目場景下如何從swagger-bootsstrap-ui切換使用knife4j
Spring Boot單服務架構
如果你是Spring Boot的單體架構,所有的服務Controller接口都是寫在一起的,那麼使用knife4j的方式就很簡單了,你只需要引入starter即可
maven中的pom.xml文件引入starter即可
<dependency>
<groupId>com.github.xiaoymin</groupId>
<artifactId>knife4j-spring-boot-starter</artifactId>
<version>2.0.1</version>
</dependency>
knife4j-spring-boot-starter主要爲我們引用的相關jar包：
knife4j-spring:Swagger增強處理類knife4j-spring-ui:swagger的增強ui文檔springfox-swagger:springfox最新2.9.2版本springfox-swagger-ui:springfox提供的uispringfox-bean-validators：springfxo 驗證支持組件
此時,位於包路徑com.github.xiaoymin.knife4j.spring.configuration.Knife4jAutoConfiguration.java類會爲我們開啓Swagger的增強註解,您只需要在項目中創建Swagger的Docket對象即可
@Configuration
@EnableSwagger2
@EnableKnife4j
@Import(BeanValidatorPluginsConfiguration.class)
public class SwaggerConfiguration {
}
Spring Cloud微服務架構
在微服務架構下,引入微服務的starter
<dependency>
<groupId>com.github.xiaoymin</groupId>
<artifactId>knife4j-micro-spring-boot-starter</artifactId>
<version>2.0.1</version>
</dependency>
knife4j-micro-spring-boot-starter 的區別在於去掉了Swagger的前端UI包,只引入了後端的Java代碼模塊
主要包含的核心模塊jar：
knife4j-spring:Swagger增強處理類springfox-swagger:springfox最新2.9.2版本springfox-bean-validators：springfxo驗證支持組件