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

時間 2019-11-09

標籤 springboot 開發單體 web shop swagger 生成 javadoc 欄目 Spring 简体版

原文原文鏈接

Swagger生成JavaDoc

在平常的工做中，特別是如今先後端分離模式之下，接口的提供形成了咱們先後端開發人員的溝通成本大量提高，由於溝通不到位，不及時而形成的[撕幣]事件都成了平常工做。特別是不少的開發人員不擅長溝通，形成的結果就會讓本身特別的痛苦，也讓合做人員恨的牙根癢癢。爲告終束戰火蔓延，同時爲了提高開發人員的滿意度，Swagger應運而生。html

什麼是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.java

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

集成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，能夠看到它依賴的版本信息。github

<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註解spring

@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文件配置。shell

# 配置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,能夠看到以下：能夠看到，咱們在yml文件中配置的信息，展現在了頁面的頂部，點擊用戶管理: 從上圖能夠看出，咱們的/users/create接口展出出來，而且要傳入的參數，請求類型等等信息都已經展現在上圖中。可是，要傳遞的參數是什麼意思，都是咱們的字段信息，咱們要如何讓它更友好的展現給調用方呢？讓咱們繼續完善咱們的文檔信息：apache

完善說明信息

在咱們建立用戶的時候，須要傳遞一個com.liferunner.dto.UserRequestDTO對象，這個對象的屬性以下：bootstrap

@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提供給咱們用以說明字段和文檔說明的註解。segmentfault

@Api 表示對外提供API
@ApiIgnore 表示不對外展現，可用於類和方法
@ApiOperation 就是指的某一個API下面的CURD動做
@ApiResponses 描述操做可能出現的異常狀況
@ApiParam 描述傳遞的單參數信息
@ApiModel 用來描述java object的屬性說明
@ApiModelProperty 描述object 字段說明全部的使用，均可以進入到相關的註解的具體class去查看全部的屬性信息，都比較簡單，這裏就不作具體描述了。想要查看更多的屬性說明，你們能夠進入：Swagger屬性說明傳送門。

配置完以後，重啓應用，刷新UI頁面：上圖中紅框圈定的都是咱們從新配置的說明信息，足夠簡單明瞭吧～

集成更好用的UI界面

針對於API說明來講，咱們上述的信息已經足夠優秀了，但是作技術，咱們應該追求的是更加極致的地步，上述的UI界面在咱們提供大批量用戶接口的時候，友好型就有那麼一丟丟的欠缺了，如今給你們再介紹一款更好用的開源Swagger UI，有請swagger-bootstrap-ui。咱們從上圖能夠看到，這個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,效果以下：點擊建立用戶：上述的效果是否是更符合咱們的審美了～到此爲止，咱們使用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數據，以下圖：
<outputdir>src/docs/asciidoc/generated-doc</outputdir> 設置咱們要生成的目錄地址

執行命令:

expensive-shop\mscx-shop-api&gt;mvn swagger2markup:convertSwagger2markup

要是你們以爲命令太長了，也能夠點擊IDEA => Maven => mscx-shop-api => Plugins => swagger2markup => swagger2markup:convertSwagger2markup 就能夠執行啦，以下圖：生成結果以下： 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&gt;mvn asciidoctor:process-asciidoc

生成結果以下：打開overview.html,以下：

至此，咱們的文檔就已經所有生成了！

下節預告

下一節咱們將繼續開發咱們的用戶登陸以及首頁信息的部分展現，在過程當中使用到的任何開發組件，我都會經過專門的一節來進行介紹的，兄弟們末慌！

gogogo！

奔跑的人生 | 博客園 | segmentfault | spring4all | csdn | 掘金 | OSChina | 簡書 | 頭條 | 知乎 | 51CTO

相關標籤/搜索

每日一句

每一个你不满意的现在，都有一个你没有努力的曾经。