swagger簡介

swagger官方對其軟件定位于API構建工具茉帅。
它本身包含的功能很多网梢，官方給出的功能特點有：
API設計： 可以使用swagger提供的編輯工具酝碳，開發(fā)API的接口申明遂跟。
構建工具： 并通過反向工程生成各語言API接口的腳手架代碼蓬推。
文檔工具： 可以通過swagger的規(guī)范將代碼中的注釋生成格式化文檔。
測試工具： 可以通過使用swagger-ui工具俺抽，直接調用基于swagger規(guī)范開發(fā)的API接口進行測試敞映。
更多內容請訪問官網(wǎng)了解 [https://swagger.io/]。

微服務基于swagger自動生成文檔原理

在微服務中通過引入swagger核心基礎組件磷斧，使用swagger的注解在微服務的接口和使用的模型上添加API規(guī)范說明振愿。
接口說明

@Deprecated
@Api(value = "XX平臺服務適配接口")
public interface MidSysServiceV2 {
    /**
     * xx接口
     *
     * @param channel
     *            調用渠道
     * @param mainRiskCode
     *            主險code
     * @param riskNo
     *            保單號
     * @param midSysOrderNo
     *            投保時的核心訂單號
     */
    @ApiOperation(value = "撤單接口", notes = "")
    public DubboResultV1<String> doOrderCancel(
            @ApiParam(name = "channel", value = "調用渠道", required = true) SourceChannel channel,
            @ApiParam(name = "mainRiskCode", value = "主險編碼", required = true) String mainRiskCode, 
            @ApiParam(name = "riskNo", value = "保單號", required = true) String riskNo,
            @ApiParam(name = "midSysOrderNo", value = "投保時的核心訂單號", required = true) String midSysOrderNo);

模型說明

@ApiModel(value="SourceChannel",description="渠道對象")
public enum SourceChannel {
    HXCP("hxcx", "小程序"),
    HXYD("hxyd", "移動官網(wǎng)"),
    HXGW("hxgw", "PC官網(wǎng)"),
    HXJDT("hxjdt", "經(jīng)代通");
    
    @ApiModelProperty(value = "渠道編碼", name = "code", example = "hxjdt")
    private String code;
    @ApiModelProperty(value = "渠道描述", name = "descript", example = "經(jīng)代通")
    private String descript;

在微服務啟動的時候，dubbo-swagger組件通過遍歷工作中dubbo的實現(xiàn)類弛饭。
通過反射機制獲取swagger的注解信息冕末，將注釋信息生成為基于json格式的元數(shù)據(jù)信息。

{"swagger":"2.0","info":{"version":"","title":"hxjk-haioums-provider-dev","contact":{"name":"yidonghulian-dev"}},"basePath":"/","paths":{"/h/com.ab.hxjk.haioums.dubbo.api.MidSysServiceV2/doNoCardPay":{"post":{"tags":["MidSysServiceV2"],"summary":"無卡支付接口","description":"DubboResultV1 
......

并且還為dubbo接口生成了REST風格的api,代理微服務的訪問侣颂。

Mapped "{[/h/{interfaceClass}/{methodName}],produces=[application/json;charset=utf-8]}" onto public org.springframework.http.ResponseEntity<java.lang.String> com.deepoove.swagger.dubbo.web.DubboHttpController.invokeDubbo(java.lang.String,java.lang.String,javax.servlet.http.HttpServletRequest,javax.servlet.http.HttpServletResponse) throws java.lang.Exception

大概流程就是引入的組件中有一個controller類档桃，將REST請求中的json參數(shù)，轉換為對應的POJO模型對象憔晒，并通過dubbo服務的消費方連接到自己提供的服務提供方藻肄，產生服務調用销凑。

配置

首先在微服務接口工程中引入swagger的核心包。

        <dependency>
            <groupId>io.swagger</groupId>
            <artifactId>swagger-core</artifactId>
            <version>1.5.16</version>
        </dependency>       

為API接口及模型添加注解

常用注解有：

- @Api()用于類仅炊； 
表示標識這個類是swagger的資源 
- @ApiOperation()用于方法斗幼； 
表示一個http請求的操作 
- @ApiParam()用于方法，參數(shù)抚垄，字段說明蜕窿； 
表示對參數(shù)的添加元數(shù)據(jù)（說明或是否必填等） 
- @ApiModel()用于類 
表示對類進行說明，用于參數(shù)用實體類接收 
- @ApiModelProperty()用于方法呆馁，字段 
表示對model屬性的說明或者數(shù)據(jù)操作更改 
- @ApiIgnore()用于類桐经，方法，方法參數(shù) 
表示這個方法或者類被忽略 
- @ApiImplicitParam() 用于方法 
表示單獨的請求參數(shù) 
- @ApiImplicitParams() 用于方法浙滤，包含多個 @ApiImplicitParam

在微服務接口實現(xiàn)工程中引入swagger-dubbo包

        <dependency>
            <groupId>com.deepoove</groupId>
            <artifactId>swagger-dubbo</artifactId>
            <version>2.0.1</version>
        </dependency>       

并在工程中添加對組件的配置（因為工程是springboot阴挣，所以是基于配置類來實現(xiàn)的配置。）

@DubboComponentScan(basePackages = { "com.ab.hxjk.haioums.dubbo" })  //dubbo實現(xiàn)類的路徑
@EnableDubboSwagger //生成api-docs及調用的REST接口
@Configuration
public class SwaggerConfig {

}

*備注：如果需要通過swagger-ui工程調用微服務工程swagger的REST接口纺腊，需要申請工程支付跨域調用 畔咧。

@Configuration
public class CorsConfig {
    @Bean
    public FilterRegistrationBean corsFilter() {
        UrlBasedCorsConfigurationSource source = new UrlBasedCorsConfigurationSource();
        CorsConfiguration config = new CorsConfiguration();
        config.setAllowCredentials(true);
        // 設置你要允許的網(wǎng)站域名，如果全允許則設為 *
        config.addAllowedOrigin("*");
        // 如果要限制 HEADER 或 METHOD 請自行更改
        config.addAllowedHeader("*");
        config.addAllowedMethod("*");
        source.registerCorsConfiguration("/**", config);
        FilterRegistrationBean bean = new FilterRegistrationBean(new CorsFilter(source));
        // 這個順序很重要哦揖膜，為避免麻煩請設置在最前
        bean.setOrder(0);
        return bean;
    }
}

工程啟動以后就可以訪問swagger的REST接口了誓沸。

可以通過相對路徑/swagger-dubbo/api-docs獲取API的元數(shù)據(jù)信息。
也可以通過相對路徑/h/{DUBBO_SERVICE_INTERFACE_FULLPACKAGE_PATH}/{DUBBO_SERVICE_INTERFACE_METHOD}調用微服務壹粟。

配置swagger-ui

可以通過docker的現(xiàn)成鏡像swaggerapi/swagger-ui [https://hub.docker.com/r/swaggerapi/swagger-ui/]運行swagger-ui客戶端拜隧，或是通過下載工程[https://codeload.github.com/Sayi/swagger-dubbo/zip/master]，將工程中的子項目swagger-dubbo-master\swagger-dubbo-example\dubbo-provider-springboot進行修改使用趁仙。該工程我已經(jīng)重構提交到http://gitlab.ab.com/JKX/HXYDHL/microservices/tree/master/swagger-dubbo-ui上了洪添。
下面是運行界面：
可以通過在swagger-ui的首頁中訪問微服務REST接口/api-docs，獲取接口API信息雀费。

swagger-dubbo-images1.png

swagger-dubbo-images2.png