跳到主要內容

多應用下 Swagger 的使用，這可能是最好的方式!

問題


微服務化的時代，我們整個項目工程下面都會有很多的子系統，對於每個應用都有暴露 Api 接口文檔需要，這個時候我們就會想到 Swagger 這個優秀 jar 包。但是我們會遇到這樣的問題，假如說我們有5個應用，難道說我們每個模塊下面都要去引入這個 jar 包嗎？我作為一個比較懶的程序感覺這樣好麻煩，於是乎我思考了一種我認為比較好的方式，如果大家覺得有什麼不太好的地方希望指正，謝謝！


基礎


開始之前大家首先要了解一些基礎，主要有以下幾個方面:



  1. 單應用下 Swagger 的集成與使用

  2. 條件裝配 @Conditional 介紹

  3. 配置文件參數獲取 @ConfigurationProperties


單體應用下 Swagger 集成與使用

關於這部分從3方面講起分別是：什麼是、為什麼、如何用


什麼是 Swagger ？

Swagger 是一個規範且完整的框架，用於生成、描述、調用和可視化 RESTful 風格的 Web 服務。


為什麼使用 Swagger ？

主要的優點:



  1. 支持 API 自動生成同步的在線文檔：使用 Swagger 后可以直接通過代碼生成文檔，不再需要自己手動編寫接口文檔了，對程序員來說非常方便，可以節約寫文檔的時間去學習新技術。

  2. 提供 Web 頁面在線測試 API：光有文檔還不夠，Swagger 生成的文檔還支持在線測試。參數和格式都定好了，直接在界面上輸入參數對應的值即可在線測試接口。


缺點的話就是但凡引入一個 jar 需要去了解下原理和使用，對於這個缺點我感覺相比於優點就是大巫見小巫，我簡單看了一下源碼，其實不算太難。


如何使用 Swagger

關於 Swagger 的使用其實也就是3板斧，大家一定很熟悉的；


第一板斧就是引入 jar 包，這裏我使用的是2.9.2版本


        <!-- swagger 相關 -->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>${swagger2.version}</version>
        </dependency>
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>${swagger2.version}</version>
        </dependency>

第二板斧就是SpringBoot自動掃描配置類


/**
 * SwaggerConfig
 *
 * @author wangtongzhou
 * @since 2020-06-09 09:41
 */
@Configuration
@EnableSwagger2
public class SwaggerConfig {

    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                //生產環境的時候關閉 Swagger 比較安全
                .apiInfo(apiInfo())
                .select()
                //Api掃描目錄
                .apis(RequestHandlerSelectors.basePackage("com.springboot2.learning"))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("learn")
                .description("learn")
                .version("1.0")
                .build();
    }
}

第三板斧使用 Swagger 註解


/**
 * 用戶相關接口
 *
 * @author wangtongzhou
 * @since 2020-06-12 07:35
 */
@RestController
@RequestMapping("/user")
@Api(value = "用戶相關接口")
public class UserController {

    @PostMapping("/")
    @ApiOperation("添加用戶的接口")
    @ApiImplicitParams({
            @ApiImplicitParam(name = "userName", value = "用戶名", defaultValue =
                    "wtz"),
            @ApiImplicitParam(name = "age", value = "年齡", defaultValue = "20")
    })
    public User addUser(String userName, Integer age) {
        User user = new User();
        user.setAge(age);
        user.setUserName(userName);
        return user;
    }

    @GetMapping("/{userId}")
    @ApiOperation("根據用戶id查詢用戶信息")
    @ApiImplicitParam(name = "userId", value = "用戶id", defaultValue = "20")
    public User queryUserByUserId(@PathVariable Long userId) {
        User user = new User();
        user.setUserId(userId);
        return user;
    }
}
/**
 * 用戶實體
 *
 * @author wangtongzhou
 * @since 2020-06-12 07:45
 */
@ApiModel
public class User {

    @ApiModelProperty(value = "用戶名稱")
    private String userName;

    @ApiModelProperty(value = "年齡")
    private Integer age;

    @ApiModelProperty(value = "用戶id")
    private Long userId;

    public String getUserName() {
        return userName;
    }

    public void setUserName(String userName) {
        this.userName = userName;
    }

    public Integer getAge() {
        return age;
    }

    public void setAge(Integer age) {
        this.age = age;
    }

    public Long getUserId() {
        return userId;
    }

    public void setUserId(Long userId) {
        this.userId = userId;
    }
}

效果如下:

實體註解

接口描述

接口參數

執行接口

返回地址
條件裝配 @Conditional 介紹

@Conditional 是Spring4.0提供的註解，位於 org.springframework.context.annotation 包內，它可以根據代碼中設置的條件裝載不同的bean。比如說當一個接口有兩個實現類時，我們要把這個接口交給Spring管理時通常會只選擇實現其中一個實現類，這個時候我們總不能使用if-else吧，所以這個@Conditional的註解就出現了。


@Retention(RetentionPolicy.RUNTIME)
@Target({ElementType.TYPE, ElementType.METHOD})
public @interface Conditional {

    Class<? extends Condition>[] value();

}

使用方法

這裏介紹一個MySQL和Oracle選擇方式，開始之前首先在properties文件中增加sql.name=mysql的配置，接下來步驟如下



  1. 實現Conditional接口, 實現matches方法


/**
 * mysql條件裝配
 *
 * @author wangtongzhou
 * @since 2020-06-13 08:01
 */
public class MysqlConditional implements Condition {
    @Override
    public boolean matches(ConditionContext context, AnnotatedTypeMetadata metadata) {
        String sqlName = context.getEnvironment().getProperty("sql.name");
        if ("mysql".equals(sqlName)){
            return true;
        }
        return false;
    }
}
/**
 * oracle條件裝配
 *
 * @author wangtongzhou
 * @since 2020-06-13 08:02
 */
public class OracleConditional implements Condition {
    @Override
    public boolean matches(ConditionContext context, AnnotatedTypeMetadata metadata) {
        String sqlName=context.getEnvironment().getProperty("sql.name");
        if ("oracle".equals(sqlName)){
            return true;
        }
        return false;
    }
}


  1. 在需要判斷條件的bean上，加上@Conditional(***.class)即可在滿足條件的時候加載對應的類


/**
 * conditional
 *
 * @author wangtongzhou
 * @since 2020-06-13 08:01
 */
@Configuration
public class ConditionalConfig {

    @Bean
    @Conditional(MysqlConditional.class)
    public Mysql mysql() {
        return new Mysql();
    }

    @Bean
    @Conditional(OracleConditional.class)
    public Oracle oracle() {
        return new Oracle();
    }
}


  1. 調用測試


@RunWith(SpringRunner.class)
@SpringBootTest
public class ConditionalTests {

    @Autowired
    private ApplicationContext applicationContext;

    @Test
    public void test_conditional() {
        Mysql mysql = (Mysql) applicationContext.getBean("mysql");
        Assert.assertNotNull(mysql);
        Assert.assertTrue("mysql".equals(mysql.getSqlName()));
    }
}

其他擴展註解


  1. @@ConditionalOnClass({Docket.class, ApiInfoBuilder.class})
    當存在Docket和ApiInfoBuilder類的時候才加載Bean;

  2. @ConditionalOnMissingClass不存在某個類的時候才會實例化Bean;

  3. @ConditionalOnProperty(prefix = "swagger", value = "enable", matchIfMissing = true)當存在swagger為前綴的屬性，才會實例化Bean;

  4. @ConditionalOnMissingBean當不存在某個Bean的時候才會實例化;


這裏就介紹這幾個常用，org.springframework.boot.autoconfigure.condition這個下面包含全部的關於@Conditional相關的所有註解

@Conditional擴展

註解介紹
配置文件參數獲取 @ConfigurationProperties

@ConfigurationProperties是SpringBoot加入的註解，主要用於配置文件中的指定鍵值對映射到一個Java實體類上。關於這個的使用就在下面的方式引出。


比較好的方式


關於開篇中引入的問題，解題流程主要是以下3步:



  1. 抽象一個公共 Swagger jar；

  2. 如何定製化 Swagger jar；

  3. 使用定製化完成以後的 Swagger jar;


抽象一個公共 Swagger jar

主要是就是將 Swagger jar 和一些其他需要的 jar 進行引入，使其成為一個公共的模塊，軟件工程中把這個叫做單一原則；



Maven包的引入

 


    <dependencies>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter</artifactId>
        </dependency>
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
        </dependency>
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
        </dependency>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-configuration-processor</artifactId>
        </dependency>
    </dependencies>

如何定製化 Swagger jar；

定製化就是將 Swagger 相關的屬性進行配置化的處理，這裏也可以分為兩步；



  1. 將公共的屬性抽象成配置化的類，這裏就是關於@ConfigurationProperties的使用,將配置文件中的 swagger 開頭的屬性映射到配置類的屬性當中;


/**
 * Swagger基本屬性
 *
 * @author wangtongzhou
 * @since 2020-05-24 16:58
 */
@ConfigurationProperties("swagger")
public class SwaggerProperties {

    /**
     * 子系統
     */
    private String title;

    /**
     * 描述
     */
    private String description;

    /**
     * 版本號
     */
    private String version;

    /**
     * api包路徑
     */
    private String basePackage;

    public String getTitle() {
        return title;
    }

    public SwaggerProperties setTitle(String title) {
        this.title = title;
        return this;
    }

    public String getDescription() {
        return description;
    }

    public SwaggerProperties setDescription(String description) {
        this.description = description;
        return this;
    }

    public String getVersion() {
        return version;
    }

    public SwaggerProperties setVersion(String version) {
        this.version = version;
        return this;
    }

    public String getBasePackage() {
        return basePackage;
    }

    public SwaggerProperties setBasePackage(String basePackage) {
        this.basePackage = basePackage;
        return this;
    }
}


  1. 公共屬性賦值配置到 Swagger 的配置類中，該配置類中進行一些類條件的判斷和插件Bean是否已經注入過，然後就是將配置類中的屬性，賦值到 Swagger 的初始化工程中；


/**
 * Swagger自動配置類
 *
 * @author wangtongzhou
 * @since 2020-05-24 16:35
 */
@Configuration
@EnableSwagger2
@ConditionalOnClass({Docket.class, ApiInfoBuilder.class})
@ConditionalOnProperty(prefix = "swagger", value = "enable", matchIfMissing = true)
@EnableConfigurationProperties(SwaggerProperties.class)
public class SwaggerConfig {

    @Bean
    @ConditionalOnMissingBean
    public SwaggerProperties swaggerProperties() {
        return new SwaggerProperties();
    }

    @Bean
    public Docket createRestApi() {
        SwaggerProperties properties = swaggerProperties();
        return new Docket(DocumentationType.SWAGGER_2)
                //生產環境的時候關閉 Swagger 比較安全
                .apiInfo(apiInfo(properties))
                .select()
                //Api掃描目錄
                .apis(RequestHandlerSelectors.basePackage(properties.getBasePackage()))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo(SwaggerProperties properties) {
        return new ApiInfoBuilder()
                .title(properties.getTitle())
                .description(properties.getDescription())
                .version(properties.getVersion())
                .build();
    }

}

完成以上兩步，就完成了 Swagger 模塊的定製化開發，接下來還要做一件事情，作為一個公共的模塊，我們要讓他自己進行自動化裝配，解放我們的雙手，我們在 resources 目錄下增加一個 spring.factories 配置文件，內容如下:


org.springframework.boot.autoconfigure.EnableAutoConfiguration=\
  com.springcloud.study.swagger.config.SwaggerConfig

到此我們完成所有的開發;


使用定製化完成以後的 Swagger jar;

關於使用也分為兩步，



  1. 引入 jar;


        <dependency>
            <groupId>com.springcloud.study</groupId>
            <artifactId>common-swagger</artifactId>
            <version>1.0-SNAPSHOT</version>
        </dependency>


  1. 定製化的屬性配置;


# Swagger 配置項
swagger:
  title: 用戶模塊
  description: 用戶子系統
  version: 1.0.0
  base-package: com.springcloud.study.user.controller

完成這兩步就可以開啟正常的使用了；


後續的規劃



  1. 註解整理
    後續會將 Spring 註解進行一個統一的整理，包含一些使用說明或者原理等等，希望到時候能幫助到大家吧，目前計劃兩周一個吧；

  2. 開源項目
    Spring Cloud 的學習過於碎片化，希望通過自己搞一個開源項目，提升對各個組件的掌握能力，同時也能產出一套通用化權限管理系統，具備很高的靈活性、擴展性和高可用性，並且簡單易用，這塊是和未來做企業数字化轉型相關的事是重合的，慢慢的會做一些企業級通用化的的功能開發；前端部分的話希望是採用Vue,但是這塊有一個學習成本，還沒有進行研究，目前還沒排上日程。整體的里程碑是希望在6.22離職之前完成整套後端的開發，7月中旬完成第一次Commit。


點點關注


這邊文章限於篇幅，過多的關注於使用了，後續會把上面幾個註解的原理分析講講，歡迎大家點點關注，點點贊，感謝!

本站聲明:網站內容來源於博客園,如有侵權,請聯繫我們,我們將及時處理

【其他文章推薦】



※為什麼 USB CONNECTOR 是電子產業重要的元件?



※網頁設計一頭霧水該從何著手呢? 台北網頁設計公司幫您輕鬆架站!



※台北網頁設計公司全省服務真心推薦



※想知道最厲害的網頁設計公司"嚨底家"!



※推薦評價好的iphone維修中心



Orignal From: 多應用下 Swagger 的使用，這可能是最好的方式!

留言

張貼留言

這個網誌中的熱門文章

TOYOTA將與FirstElement合作建立加氣站

據AUTONET報導，TOYOTA將與能源公司FirstElement攜手合作加氫站網絡的架設，預計2015-2016年能夠建成20多處的加氣站，並能在2024年實現擴建至100座的計畫。 TOYOTA於2013年底東京車展發表準量產版的FCV Concept，此後又藉由年初的2014 CES消費電子展預告2015年將率先投入北美市場販售，因此對於加氫站等後勤網絡的建設排上日程。 其實在過去的20年來，TOYOTA就已持續針對氫燃料電池進行研發，自2002年以來便投入一系列的測試車輛於北美進行實測，隨著技術的突破，使得氫燃料電池技術成本大幅下修，終於達到原廠量產的預期。 儘管FCV（氫燃料電池車）最終量產版本的相關數據原廠尚未公開，但參考FCV Concept所呈現的數據就相當令人滿意。 動力來源為分別藏在車身底下的氫燃料儲存槽及電池，具備等同於136hp馬力的100kW輸出功率，需花費10秒才能完成100km/h的加速衝刺，滿電的情況下續航力約可達到482km，而且僅需3-5分鐘的時間便能將儲存槽加滿，省去了傳統電池充電耗時的問題。 重點是氫燃料電池是以氫或含氫物質結合氧所形成的一種燃料電池，在化學反應之後僅會產生電流及水且完全沒有污染。 動力來源為分別藏在車身底下的氫燃料儲存槽及電池（圖片來源：AUTONET） 本站聲明:網站內容來源於EnergyTrend https://www.energytrend.com.tw/ev/,如有侵權,請聯繫我們,我們將及時處理 【其他文章推薦】 ※ 新北清潔 公司,居家、辦公、裝潢細清專業服務 ※別再煩惱 如何寫文案 ,掌握八大原則! ※ 網頁設計 一頭霧水該從何著手呢? 台北網頁設計 公司幫您輕鬆架站! ※超省錢 租車 方案 ※教你寫出一流的 銷售文案 ? Orignal From: TOYOTA將與FirstElement合作建立加氣站
張貼留言
閱讀完整內容

有了四步解題法模板，再也不害怕動態規劃！（看不懂算我輸）

導言 動態規劃問題一直是算法面試當中的重點和難點，並且動態規劃這種通過空間換取時間的算法思想在實際的工作中也會被頻繁用到，這篇文章的目的主要是解釋清楚 什麼是動態規劃 ，還有就是面對一道動態規劃問題，一般的 思考步驟 以及其中的注意事項等等，最後通過幾道題目將理論和實踐結合。 什麼是動態規劃 如果你還沒有聽說過動態規劃，或者僅僅只有耳聞，或許你可以看看 Quora 上面的這個 回答 。 How to explain dynamic 用一句話解釋動態規劃就是 " 記住你之前做過的事 "，如果更準確些，其實是 " 記住你之前得到的答案 "。 我舉個大家工作中經常遇到的例子。 在軟件開發中，大家經常會遇到一些系統配置的問題，配置不對，系統就會報錯，這個時候一般都會去 Google 或者是查閱相關的文檔，花了一定的時間將配置修改好。 過了一段時間，去到另一個系統，遇到類似的問題，這個時候已經記不清之前修改過的配置文件長什麼樣，這個時候有兩種方案，一種方案還是去 Google 或者查閱文檔，另一種方案是借鑒之前修改過的配置，第一種做法其實是萬金油，因為你遇到的任何問題其實都可以去 Google，去查閱相關文件找答案，但是這會花費一定的時間，相比之下，第二種方案肯定會更加地節約時間，但是這個方案是有條件的，條件如下： 之前的問題和當前的問題有着關聯性，換句話說，之前問題得到的答案可以幫助解決當前問題 需要記錄之前問題的答案 當然在這個例子中，可以看到的是，上面這兩個條件均滿足，大可去到之前配置過的文件中，將配置拷貝過來，然後做些細微的調整即可解決當前問題，節約了大量的時間。 不知道你是否從這些描述中發現，對於一個動態規劃問題，我們只需要從兩個方面考慮，那就是 找出問題之間的聯繫 ，以及 記錄答案 ，這裏的難點其實是找出問題之間的聯繫，記錄答案只是順帶的事情，利用一些簡單的數據結構就可以做到。 概念 上面的解釋如果大家可以理解的話，接    動態規劃 算法是通過拆分問題，定義問題狀態和狀態之間的關係，使得問題能夠以遞推（或者說分治）的方式去解決。它的幾個重要概念如下所述。    階段： 對於一個完整的問題過程，適當的切分為若干個相互聯繫的子問題，每次在求解一個子問題...
張貼留言
閱讀完整內容

數據資產的玄學、顯學

數據就是資產，這個道理在商業領域並不難懂。 比如國外有聚焦金融數據的彭博，國內也有萬德，早期靠着人工錄入、整理數據的方式，聚集了龐大的數據庫，成為投資公司的必備；而聚焦學術文獻等知識數據的知網，不僅舒舒服服賺差價，還能涉嫌壟斷被處罰。 但數據資產這個理念，在全社會得到認可，也非一蹴而就，而是一波一波的普及、深化。 2011年，麥肯錫發布報告，認為"大數據Big Data已成為當今競爭、創新、生產效率提升的關鍵基礎"。一時間，大數據，成為業內熱點。數據，大家都懂；大，有什麼區別？ 聚焦大數據的創業公司紛紛成立，時任美國總統的奧巴馬也在2012年3月宣布了"大數據研究與發展先導計劃"，雖然投資額僅2億美元，但有評論認為這和上世紀90年代的信息公路計劃相媲美。 而不管大的是什麼，至少一個確定的趨勢是，數據資產，越來越值錢。 這股科技新風也來到中國。本着"懂不懂先不說，有新趨勢就先干"的大A，也漸漸熱鬧起來。比如擁有消費者購買記錄的百貨公司，雖然還處於電商取代線下的衰退趨勢中，但投資者還是興奮地給了"估值重構"的機會，2013年7月份，也曾有過股價快速漲一倍的戰績。 而最"得勢"的當屬銀之傑，公司通過收購億美軟通，為企業向用戶發送短信，每年發送量超過100億條。每一條短信，在投資人眼裡，都是金燦燦的"數據資產"。再疊加科技牛市buff，銀之傑受到投資者的狂熱追捧。從2012年底起，兩年半漲幅近100倍。一個字，絕。兩個字，瘋狂。 2015年4月，我國首家大數據交易所——貴陽大數據交易所成立，對數據資產的探索，又邁出了關鍵一步。成立當天就完成了第一筆數據交易，交易所管理層也雄心勃勃，提出在3～5年內將日交易額推到100億元的規模。 蜂擁而至的故事，結局似乎都差不多。2016年，Gartner在報告中警告：許多公司正打算削減大數據項目投入。 百貨行業沒有避開電商的衝擊，業績也沒有被數據資產改善；而短信等數據，也讓投資人清醒，有的數據是資產，有的只是01代碼，或者只是投資人情緒的載體。而在大數據領域創業的公司，也有一些融了FGH輪之後，不得不賣服務器來改善現金流。而貴陽大數據中心也在2022年8月，才實現了數據交易規模...
張貼留言
閱讀完整內容