swagger简介

swagger官方对其软件定位于API构建工具。
它本身包含的功能很多，官方给出的功能特点有：
API设计： 可以使用swagger提供的编辑工具，开发API的接口申明。
构建工具： 并通过反向工程生成各语言API接口的脚手架代码。
文档工具： 可以通过swagger的规范将代码中的注释生成格式化文档。
测试工具： 可以通过使用swagger-ui工具，直接调用基于swagger规范开发的API接口进行测试。
更多内容请访问官网了解 [https://swagger.io/]。

微服务基于swagger自动生成文档原理

在微服务中通过引入swagger核心基础组件，使用swagger的注解在微服务的接口和使用的模型上添加API规范说明。
接口说明

@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", "移动官网"),
    HXGW("hxgw", "PC官网"),
    HXJDT("hxjdt", "经代通");
    
    @ApiModelProperty(value = "渠道编码", name = "code", example = "hxjdt")
    private String code;
    @ApiModelProperty(value = "渠道描述", name = "descript", example = "经代通")
    private String descript;

在微服务启动的时候，dubbo-swagger组件通过遍历工作中dubbo的实现类。
通过反射机制获取swagger的注解信息，将注释信息生成为基于json格式的元数据信息。

{"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参数，转换为对应的POJO模型对象，并通过dubbo服务的消费方连接到自己提供的服务提供方，产生服务调用。

配置

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

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

为API接口及模型添加注解

常用注解有：

- @Api()用于类； 
表示标识这个类是swagger的资源 
- @ApiOperation()用于方法； 
表示一个http请求的操作 
- @ApiParam()用于方法，参数，字段说明； 
表示对参数的添加元数据（说明或是否必填等） 
- @ApiModel()用于类 
表示对类进行说明，用于参数用实体类接收 
- @ApiModelProperty()用于方法，字段 
表示对model属性的说明或者数据操作更改 
- @ApiIgnore()用于类，方法，方法参数 
表示这个方法或者类被忽略 
- @ApiImplicitParam() 用于方法 
表示单独的请求参数 
- @ApiImplicitParams() 用于方法，包含多个 @ApiImplicitParam

在微服务接口实现工程中引入swagger-dubbo包

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

并在工程中添加对组件的配置（因为工程是springboot，所以是基于配置类来实现的配置。）

@DubboComponentScan(basePackages = { "com.ab.hxjk.haioums.dubbo" })  //dubbo实现类的路径
@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);
        // 设置你要允许的网站域名，如果全允许则设为 *
        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的元数据信息。
也可以通过相对路径/h/{DUBBO_SERVICE_INTERFACE_FULLPACKAGE_PATH}/{DUBBO_SERVICE_INTERFACE_METHOD}调用微服务。

配置swagger-ui

可以通过docker的现成镜像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进行修改使用。该工程我已经重构提交到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