最近工作上需要用Swagger導出接口文檔
經過查找資料總結了一下:
Swagger簡介
1、是一款讓你更好的書寫API文檔的規範且完整框架。
2、提供描述、生產、消費和可視化RESTful Web Service。
3、是由龐大工具集合支撐的形式化規範。這個集合涵蓋了從終端用戶接口、底層代碼庫到商業API管理的方方面面。
簡單來說,Swagger是一個幫助開發人員編寫接口文檔的工具,它可以幫你自動生成接口文檔。
Swagger使用
項目中使用Swagger有兩種方法
1.**
使用第三方依賴
**
(1) pom.xml文件引入依賴:
<dependency>
<groupId>com.spring4all</groupId>
<artifactId>swagger-spring-boot-starter</artifactId>
<version>1.7.0.RELEASE</version>
(2)在Spring Boot項目的啓動類上添加@EnableSwagger2註解,api方法中添加註解。
2.使用官方依賴
① pom.xml文件引入依賴:
io.springfox springfox-swagger2 2.7.0 io.springfox springfox-swagger-ui 2.7.0② 編寫Swagger控制類
注意:swagger scan base package,這是掃描註解的配置,即你的API接口位置。需要修改爲實際項目的Api位置
③ 在Spring Boot項目的啓動類上添加@EnableSwagger2註解,api方法中添加註解。
3訪問api doc 路由
項目啓動後可以打開瀏覽器訪問:
頁面圖下:
訪問地址爲:http://localhost:8080/swagger-ui.html(端口號應改爲實際項目端口號)
注:生成靜態文檔使用的url爲紅色框中url,而不是swagger-ui.html
圖中紅色框地址是默認路由,訪問路由可以進行配置:
application.yml中聲明:
springfox.documentation.swagger.v2.path: /api-docs
/api-docs就是自定義的路由,可以自定義
生成的接口文檔可以在線進行接口測試
*需要注意的是當前日誌文檔是動態的,項目啓動纔可以以網頁方式訪問
4
Swagger常用Api
1、api標記
Api 用在類上,說明該類的作用。可以標記一個Controller類做爲swagger 文檔資源,使用方式:
@Api(value = “/user”, description = “Operations about user”)
2、ApiOperation標記
ApiOperation:用在方法上,說明方法的作用,每一個url資源的定義,使用方式:
@ApiOperation(
value = “Find purchase order by ID”,
notes = “For valid response try integer IDs with value <= 5 or > 10. Other values will generated exceptions”,
response = Order,
tags = {“Pet Store”})
3、ApiParam標記
ApiParam請求屬性,使用方式:
public ResponseEntity createUser(@RequestBody @ApiParam(value = “Created user object”, required = true) User user)
1
4、ApiResponse
ApiResponse:響應配置,使用方式:
@ApiResponse(code = 400, message = “Invalid user supplied”)
5、ApiResponses
ApiResponses:響應集配置,使用方式:
@ApiResponses({ @ApiResponse(code = 400, message = “Invalid Order”) })
6、ResponseHeader
響應頭設置,使用方法
@ResponseHeader(name=“head1”,description=“response head conf”)
Swagger生成靜態接口文檔
上面生成的接口文檔是動態的,可以方便開發人員進行接口測試,如果想要生成靜態文檔還需要額外的配置。
生成靜態文檔也有兩種方法
1.編寫java代碼生成
2.Maven插件完成
編寫java代碼生成:
1)Pom.xml文件中添加依賴
<dependency>
<groupId>io.github.swagger2markup</groupId>
<artifactId>swagger2markup</artifactId>
<version>1.3.1</version>
</dependency>
<dependency>
<groupId>ch.netzwerg</groupId>
<artifactId>paleo-core</artifactId>
<version>0.10.2</version>
</dependency>
<dependency>
<groupId>io.vavr</groupId>
<artifactId>vavr</artifactId>
<version>0.9.2</version>
</dependency>
注:Swagger2Markup是Github上的一個開源項目。該項目主要用來將Swagger自動生成的文檔轉換成幾種流行的格式以便於靜態部署和使用,比如:AsciiDoc、Markdown、Confluence。
2)編寫單元測試用例生成文檔(執行test測試方法生成文檔)
import io.github.swagger2markup.GroupBy;
import io.github.swagger2markup.Language;
import io.github.swagger2markup.Swagger2MarkupConfig;
import io.github.swagger2markup.Swagger2MarkupConverter;
import io.github.swagger2markup.builder.Swagger2MarkupConfigBuilder;
import io.github.swagger2markup.markup.builder.MarkupLanguage;
import org.junit.Test;
import org.junit.runner.RunWith;
import org.springframework.boot.test.context.SpringBootTest;
import org.springframework.test.context.junit4.SpringRunner;
import java.net.URL;
import java.nio.file.Paths;
@RunWith(SpringRunner.class)
@SpringBootTest(webEnvironment = SpringBootTest.WebEnvironment.DEFINED_PORT)
public class SwaggerTo {
/**
* 生成AsciiDocs格式文檔
* @throws Exception
*/
@Test
public void generateAsciiDocs() throws Exception {
// 輸出Ascii格式
Swagger2MarkupConfig config = new Swagger2MarkupConfigBuilder()
.withMarkupLanguage(MarkupLanguage.ASCIIDOC)
.withOutputLanguage(Language.ZH)
.withPathsGroupedBy(GroupBy.TAGS)
.withGeneratedExamples()
.withoutInlineSchema()
.build();
Swagger2MarkupConverter.from(new URL("http://localhost:8016/v2/api-docs"))
.withConfig(config)
.build()
.toFolder(Paths.get("./docs/asciidoc/generated"));
}
/**
* 生成Markdown格式文檔
* @throws Exception
*/
@Test
public void generateMarkdownDocs() throws Exception {
// 輸出Markdown格式
Swagger2MarkupConfig config = new Swagger2MarkupConfigBuilder()
.withMarkupLanguage(MarkupLanguage.MARKDOWN)
.withOutputLanguage(Language.ZH)
.withPathsGroupedBy(GroupBy.TAGS)
.withGeneratedExamples()
.withoutInlineSchema()
.build();
Swagger2MarkupConverter.from(new URL("http://localhost:8016/v2/api-docs"))
.withConfig(config)
.build()
.toFolder(Paths.get("./docs/markdown/generated"));
}
/**
* 生成AsciiDocs格式文檔,並彙總成一個文件
* @throws Exception
*/
@Test
public void generateAsciiDocsToFile() throws Exception {
// 輸出Ascii到單文件
Swagger2MarkupConfig config = new Swagger2MarkupConfigBuilder()
.withMarkupLanguage(MarkupLanguage.ASCIIDOC)
.withOutputLanguage(Language.ZH)
.withPathsGroupedBy(GroupBy.TAGS)
.withGeneratedExamples()
.withoutInlineSchema()
.build();
Swagger2MarkupConverter.from(new URL("http://localhost:8016/v2/api-docs"))
.withConfig(config)
.build()
.toFile(Paths.get("./docs/asciidoc/generated/all"));
}
/**
* 生成Markdown格式文檔,並彙總成一個文件
* @throws Exception
*/
@Test
public void generateMarkdownDocsToFile() throws Exception {
// 輸出Markdown到單文件
Swagger2MarkupConfig config = new Swagger2MarkupConfigBuilder()
.withMarkupLanguage(MarkupLanguage.MARKDOWN)
.withOutputLanguage(Language.ZH)
.withPathsGroupedBy(GroupBy.TAGS)
.withGeneratedExamples()
.withoutInlineSchema()
.build();
Swagger2MarkupConverter.from(new URL("http://localhost:8016/v2/api-docs"))
.withConfig(config)
.build()
.toFile(Paths.get("./docs/markdown/generated/all"));
}
}
說明:
· MarkupLanguage.ASCIIDOC:指定了要輸出的最終格式。除了ASCIIDOC之外,還有MARKDOWN和CONFLUENCE_MARKUP
· from(new URL(“http://localhost:8080/v2/api-docs”):指定了生成靜態部署文檔的源頭配置,可以是這樣的URL形式,也可以是符合Swagger規範的String類型或者從文件中讀取的流。如果是對當前使用的Swagger項目,我們通過使用訪問本地Swagger接口的方式,如果是從外部獲取的Swagger文檔配置文件,就可以通過字符串或讀文件的方式
· toFolder(Paths.get(“src/docs/asciidoc/generated”):指定最終生成文件的具體目錄位置
注意:
1.箭頭1,此url爲訪問http://localhost:8080/swagger-ui.html得到的api,如下圖所示
2.箭頭2,此目錄必須存在,如果目錄不存在會導致生成文檔失敗
Test運行成功如下圖所示:
此時項目已經生成了文檔:
也可以選擇將生成的文檔合併顯示,然後把生成的文檔轉陳html格式或者world格式
Maven插件完成:
<plugin>
<groupId>org.asciidoctor</groupId>
<artifactId>asciidoctor-maven-plugin</artifactId>
<version>1.5.6</version>
<configuration>
<sourceDirectory>./docs/asciidoc/generated</sourceDirectory>
<outputDirectory>./docs/asciidoc/html</outputDirectory>
<headerFooter>true</headerFooter>
<doctype>book</doctype>
<backend>html</backend>
<sourceHighlighter>coderay</sourceHighlighter>
<attributes>
<!--菜單欄在左邊-->
<toc>left</toc>
<!--多標題排列-->
<toclevels>3</toclevels>
<!--自動打數字序號-->
<sectnums>true</sectnums>
</attributes>
</configuration>
</plugin>
執行該插件的asciidoctor:process-asciidoc命令之後,就能在docs/asciidoc/html目錄下生成最終可用的靜態部署HTML了。