自定義文檔

效果說明

在1.9.3版本中,swagger-bootstrap-ui為了滿足文檔的個性化配置,添加了自定義文檔功能

開發(fā)者可自定義md文件擴展補充整個系統(tǒng)的文檔說明

開發(fā)者可以在當前項目中添加一個文件夾，文件夾中存放.md格式的markdown文件,每個.md文檔代表一份自定義文檔說明

注意：自定義文檔說明必須以.md結尾的文件,其他格式文件會被忽略

例如項目結構如下：

每個.md文件中，swagger-bootstrap-ui允許一級(h1)、二級(h2)、三級(h3)標題作為最終的文檔標題

比如api.md文檔：

## 自定義文檔說明


## 效果說明


在`1.9.3`版本中,`swagger-bootstrap-ui`為了滿足文檔的個性化配置,添加了自定義文檔功能


開發(fā)者可自定義`md`文件擴展補充整個系統(tǒng)的文檔說明


開發(fā)者可以在當前項目中添加一個文件夾，文件夾中存放`.md`格式的markdown文件,每個`.md`文檔代表一份自定義文檔說明


**注意**：自定義文檔說明必須以`.md`結尾的文件,其他格式文件會被忽略

最終在swagger-bootstrap-ui的界面中,api.md的文檔標題會是自定義文檔說明

整個文檔效果如下：

如果沒有按照一級(h1)、二級(h2)、三級(h3)來設置標題,默認標題會是文件名稱，如圖上的api2.md

如何使用

Spring Boot環(huán)境

在SpringBoot環(huán)境中,首先需要在application.yml或者application.properties配置文件中配置自定義文檔目錄

如下：

swagger:
  markdowns: classpath:markdown/*

然后在Swagger的配置文件中啟用@EnableSwaggerBootstrapUi注解

如下代碼：

@Configuration
@EnableSwagger2
@EnableSwaggerBootstrapUI
public class SwaggerConfiguration {
    //more...

    
}

除了在后端開啟注解功能,在doc.html中,個性化配置里面還需要設置開啟增強功能

當然,在確保后端增強無誤的情況下,你可以直接使用快速訪問設置功能來直接啟用增強

地址輸入：http://127.0.0.1:8888/doc.html?plus=1

Spring MVC環(huán)境

在Spring MVC環(huán)境中,首先引入swagger-bootstrap-ui的jar包文件

<dependency>
  <groupId>com.github.xiaoymin</groupId>
  <artifactId>swagger-bootstrap-ui</artifactId>
  <version>1.9.3</version>
</dependency>

然后,需要在Spring的XML配置文件中注入MarkdownFiles類的實例bean

如下：

<!--注入自定義文檔的bean-->
<bean id="markdownFiles" class="io.swagger.models.MarkdownFiles" init-method="init">
    <property name="basePath" value="classpath:markdown/*"></property>
</bean>

其他例如開啟增強等操作和Spring Boot環(huán)境無異,打開doc.html即可訪問看到效果

demo示例

以上兩種不同環(huán)境的demo示例可參考swagger-bootstrap-ui-demo