自定義文檔

效果說明

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

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

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

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

例如項(xiàng)目結(jié)構(gòu)如下：

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

比如api.md文檔：

## 自定義文檔說明


## 效果說明


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


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


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


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

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

整個(gè)文檔效果如下：

如果沒有按照一級(h1)、二級(h2)、三級(h3)來設(shè)置標(biāo)題,默認(rèn)標(biāo)題會是文件名稱，如圖上的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中,個(gè)性化配置里面還需要設(shè)置開啟增強(qiáng)功能

當(dāng)然,在確保后端增強(qiáng)無誤的情況下,你可以直接使用快速訪問設(shè)置功能來直接啟用增強(qiáng)

地址輸入：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類的實(shí)例bean

如下：

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

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

demo示例

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