[springboot 開發單體web shop] 4. Swagger生成Javadoc

發表於2019-11-08
Spring BootWebSwaggerJava

Swagger生成JavaDoc

在日常的工作中，特別是現在前後端分離模式之下，介面的提供造成了我們前後端開發人員的溝通
成本大量提升，因為溝通不到位，不及時而造成的[撕幣]事件都成了日常工作。特別是很多的開發人員
不擅長溝通，造成的結果就會讓自己特別的痛苦，也讓合作人員恨的牙根癢癢。
為了結束戰火蔓延，同時為了提升開發人員的滿意度，Swagger應運而生。

什麼是Swagger

Swagger for Everyone
Simplify API development for users, teams, and enterprises with the Swagger open source and professional toolset.
Swagger open source and pro tools have helped millions of API developers, teams, and organizations deliver great APIs.

簡言之就是指使用工具集簡化使用者、團隊和企業的API開發。

整合Swagger

系統中我選擇使用的是swagger-spring-boot-starter。

該專案主要利用Spring Boot的自動化配置特性來實現快速的將swagger2引入spring boot應用來生成API文件，簡化原生使用swagger2的整合程式碼。
看得出來，我在教大家使用的都是在偷懶哦，這可不是什麼好現象。。。

新增依賴

        <!--整合Swagger2-->
        <dependency>
            <groupId>com.spring4all</groupId>
            <artifactId>swagger-spring-boot-starter</artifactId>
            <version>1.9.0.RELEASE</version>
        </dependency>

點選版本號進入swagger-spring-boot-starter/1.9.0.RELEASE/swagger-spring-boot-starter-1.9.0.RELEASE.pom，可以看到它依賴的版本資訊。

    <properties>
        <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
        <version.java>1.8</version.java>
        <version.swagger>2.9.2</version.swagger>
        <version.spring-boot>1.5.10.RELEASE</version.spring-boot>
        <version.lombok>1.18.6</version.lombok>
    </properties>

啟用功能

在我們的啟動類ApiApplication上增加@EnableSwagger2Doc註解

@SpringBootApplication
@MapperScan(basePackages = "com.liferunner.mapper")
@ComponentScan(basePackages = {"com.liferunner", "org.n3r.idworker"})
@EnableSwagger2Doc //啟動Swagger
public class ApiApplication {

    public static void main(String[] args) {
        new SpringApplicationBuilder()
                .sources(ApiApplication.class)
                .run(args);
    }

    @Autowired
    private CORSConfig corsConfig;

    /**
     * 註冊跨域配置資訊
     *
     * @return {@link CorsFilter}
     */
    @Bean
    public CorsFilter corsFilter() {
        val corsConfiguration = new CorsConfiguration();
        corsConfiguration.addAllowedOrigin(this.corsConfig.getAllowOrigin());
        corsConfiguration.addAllowedMethod(this.corsConfig.getAllowedMethod());
        corsConfiguration.addAllowedHeader(this.corsConfig.getAllowedHeader());
        corsConfiguration.setAllowCredentials(this.corsConfig.getAllowCredentials());

        val urlBasedCorsConfigurationSource = new UrlBasedCorsConfigurationSource();
        urlBasedCorsConfigurationSource.registerCorsConfiguration("/**", corsConfiguration);

        return new CorsFilter(urlBasedCorsConfigurationSource);
    }
}

配置基礎資訊

可以通過properties檔案和yml/yaml檔案配置。

# 配置swagger2
swagger:
  enabled: true #是否啟用swagger，預設：true
  title: 實戰電商api平臺
  description: provide 電商 API
  version: 1.0.0.RC
  license: Apache License, Version 2.0
  license-url: https://www.apache.org/licenses/LICENSE-2.0.html
  terms-of-service-url: http://www.life-runner.com
  contact:
    email: magicianisaac@gmail.com
    name: Isaac-Zhang
    url: http://www.life-runner.com
  base-package: com.liferunner
  base-path: /**

階段效果一

執行我們的api專案，在瀏覽器輸入：http://localhost:8088/swagger-ui.html,可以看到如下：
階段效果1
可以看到，我們在yml檔案中配置的資訊，展示在了頁面的頂部，點選使用者管理:
使用者管理
從上圖可以看出，我們的/users/create介面展出出來，並且要傳入的引數，請求型別等等資訊都已經展示在上圖中。
但是，要傳遞的引數是什麼意思，都是我們的欄位資訊，我們要如何讓它更友好的展示給呼叫方呢？讓我們繼續
完善我們的文件資訊：

完善說明資訊

在我們建立使用者的時候，需要傳遞一個com.liferunner.dto.UserRequestDTO物件，這個物件的屬性如下：

@RestController
@RequestMapping(value = "/users")
@Slf4j
@Api(tags = "使用者管理")
public class UserController {

    @Autowired
    private IUserService userService;

    @ApiOperation(value = "使用者詳情", notes = "查詢使用者")
    @ApiIgnore
    @GetMapping("/get/{id}")
    //@GetMapping("/{id}") 如果這裡設定位這樣，每次請求swagger都會進到這裡，是一個bug
    public String getUser(@PathVariable Integer id) {
        return "hello, life.";
    }

    @ApiOperation(value = "建立使用者", notes = "使用者註冊介面")
    @PostMapping("/create")
    public JsonResponse createUser(@RequestBody UserRequestDTO userRequestDTO) {
        //...
    }
}
@Data
@AllArgsConstructor
@NoArgsConstructor
@Builder
@ApiModel(value = "建立使用者DTO", description = "使用者註冊需要的引數物件")
public class UserRequestDTO {
    @ApiModelProperty(value = "使用者名稱", notes = "username", example = "isaaczhang", required = true)
    private String username;
    @ApiModelProperty(value = "註冊密碼", notes = "password", example = "12345678", required = true)
    private String password;
    @ApiModelProperty(value = "確認密碼", notes = "confimPassword", example = "12345678", required = true)
    private String confirmPassword;
}

可以看到，我們有很多通過@Apixxx開頭的註解說明，這個就是Swagger提供給我們用以說明欄位和文件說明的註解。

  • @Api 表示對外提供API
  • @ApiIgnore 表示不對外展示，可用於類和方法
  • @ApiOperation 就是指的某一個API下面的CURD動作
  • @ApiResponses 描述操作可能出現的異常情況
  • @ApiParam 描述傳遞的單引數資訊
  • @ApiModel 用來描述java object的屬性說明
  • @ApiModelProperty 描述object 欄位說明

所有的使用，都可以進入到相關的註解的具體class去檢視所有的屬性資訊，都比較簡單，這裡就不做具體描述了。想要檢視更多的屬性說明，
大家可以進入：Swagger屬性說明傳送門。

配置完之後，重啟應用，重新整理UI頁面：
階段效果二
上圖中紅框圈定的都是我們重新配置的說明資訊，足夠簡單明瞭吧～

整合更好用的UI介面

針對於API說明來說，我們上述的資訊已經足夠優秀了，可是做技術，我們應該追求的是更加極致的地步，上述的UI介面在我們提供大批量
使用者介面的時候，友好型就有那麼一丟丟的欠缺了，現在給大家再介紹一款更好用的開源Swagger UI，有請swagger-bootstrap-ui。
UI2
我們從上圖可以看到，這個UI的Star數目已經超過1.1K了，這就證明它已經很優秀了，我們接下來解開它的廬山真面目吧。

整合依賴

只需要在我們的expensive-shop\pom.xml中加入以下依賴程式碼：

        <!--一種新的swagger ui-->
        <dependency>
            <groupId>com.github.xiaoymin</groupId>
            <artifactId>swagger-bootstrap-ui</artifactId>
            <version>1.6</version>
        </dependency>

預覽效果

新增完依賴後，只需要重啟我們的應用，然後訪問http://localhost:8088/doc.html,效果如下：
階段效果3
點選建立使用者：
階段效果4
上述的效果是不是更符合我們的審美了～
到此為止，我們使用Swagger來動態生成API的效果已經全部演示完了，但是如果某一天我們要和一個不能連線檢視我們網站的客戶進行整合的時候，我們怎麼辦呢？
還是要手寫一份文件給他們嗎？ 那我們不就一樣很痛苦嗎！！！
作為程式設計師，我們是絕對不能允許這種情況發生的！
那就讓我們繼續看下去。

生成離線文件

為了不讓我們做痛苦的工作，我們既然已經在程式碼中新增了那麼多的說明資訊，是否有一種方式可以幫助我們來生成一份離線的文件呢？答案是肯定的。

開源專案swagger2markup

A Swagger to AsciiDoc or Markdown converter to simplify the generation of an up-to-date RESTful API documentation by combining documentation that’s been hand-written with auto-generated API documentation.

原始碼傳送門
documents傳送門

Swagger2Markup它主要是用來將Swagger自動生成的文件轉換成幾種流行的格式以便離線使用
格式：AsciiDoc、HTML、Markdown、Confluence

使用MAVEN外掛生成AsciiDoc文件

在mscx-shop-api\pom.xml中加入以下依賴程式碼：

<build>
        <plugins>
            <!--生成 AsciiDoc 文件(swagger2markup)-->
            <plugin>
                <groupId>io.github.swagger2markup</groupId>
                <artifactId>swagger2markup-maven-plugin</artifactId>
                <version>1.3.3</version>
                <configuration>
                    <!--這裡是要啟動我們的專案，然後抓取api-docs的返回結果-->
                    <swaggerInput>http://localhost:8088/v2/api-docs</swaggerInput>
                    <outputDir>src/docs/asciidoc/generated-doc</outputDir>
                    <config>
                        <swagger2markup.markupLanguage>ASCIIDOC</swagger2markup.markupLanguage>
                    </config>
                </configuration>
            </plugin>
        </plugins>
    </build>
  • <swaggerInput>http://localhost:8088/v2/api-docs</swaggerInput> 是為了獲取我們的api JSON資料，如下圖：

API-JSON

  • <outputDir>src/docs/asciidoc/generated-doc</outputDir> 設定我們要生成的目錄地址

執行命令:

expensive-shop\mscx-shop-api>mvn swagger2markup:convertSwagger2markup

要是大家覺得命令太長了，也可以點選`IDEA => Maven => mscx-shop-api => Plugins => swagger2markup => swagger2markup:convertSwagger2markup
`就可以執行啦，如下圖：
swagger2markup
生成結果如下：
asciidoc
adoc檔案生成好了，那麼我們使用它來生成html吧

使用MAVEN外掛生成HTML

在mscx-shop-api\pom.xml中加入以下依賴程式碼：

            <!--生成 HTML 文件-->
            <plugin>
                <groupId>org.asciidoctor</groupId>
                <artifactId>asciidoctor-maven-plugin</artifactId>
                <version>1.5.6</version>
                <configuration>
                    <sourceDirectory>src/docs/asciidoc/generated-doc</sourceDirectory>
                    <outputDirectory>src/docs/asciidoc/html</outputDirectory>
                    <backend>html</backend>
                    <sourceHighlighter>coderay</sourceHighlighter>
                    <attributes>
                        <toc>left</toc>
                    </attributes>
                </configuration>
            </plugin>
  • <sourceDirectory>src/docs/asciidoc/generated-doc</sourceDirectory> 原始檔目錄指定為我們上一節生成的adoc
  • <outputDirectory>src/docs/asciidoc/html</outputDirectory> 指定輸出目錄

執行生成命令：

\expensive-shop\mscx-shop-api>mvn asciidoctor:process-asciidoc

生成結果如下：
result html
開啟overview.html,如下：
html

至此，我們的文件就已經全部生成了！

下節預告

下一節我們將繼續開發我們的使用者登入以及首頁資訊的部分展示，在過程中使用到的任何開發元件，我都會通過專門的一節來進行介紹的，兄弟們末慌！

gogogo！

相關文章