SpringCloud配置Swagger-UI

业务代码中用到在线api工具swagger，用起来还是很方便的，记录以下在springcloud中的配置使用过程;

1、导入依赖

<springfox-swagger.version>2.7.0</springfox-swagger.version>
<swagger-annotations.version>1.5.13</swagger-annotations.version>

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

2、对于微服务的自动配置，我们要约定以下配置加载参数;

@Configuration
@EnableSwagger2
@ConditionalOnProperty({"swagger.conf.host"})
@ConfigurationProperties("swagger.conf")
@Data
public class SwaggerAutoConfig {
    private String groupName;
    private String basePackage;
    private String title;
    private String host;
    private String desc;
    private String serviceUrl;
    private String version;

    @Bean
    public Docket createRestApi() {
        List<Parameter> pars = new ArrayList<Parameter>() {
            private static final long serialVersionUID = 1L;

            {
                this.add((new ParameterBuilder()).name("gsid").description("全局会话ID(必要时使用)").modelRef(new ModelRef("string")).parameterType("header").required(false).build());
            }
        };
        return (new Docket(DocumentationType.SWAGGER_2)).groupName(this.groupName).apiInfo(this.apiInfo()).host(this.host).select().apis(RequestHandlerSelectors.basePackage(this.basePackage)).paths(PathSelectors.any()).build().globalOperationParameters(pars);
    }

    private ApiInfo apiInfo() {
        return (new ApiInfoBuilder()).title(this.title).description(this.desc).termsOfServiceUrl(this.serviceUrl).version(this.version + LocalDateTime.now()).build();
    }

}

3、然后，我们在springcloud的配置中文中加入对应的引发自动配置的参数,上面类中注解上的配置前缀

在application.properties或者application.yml(这个看使用的配置文件是何种类型，总之加导配置中去):

server.port=10100

host=127.0.0.1
swagger.conf.host=${host}:${server.port}
swagger.conf.group-name=bracelet-rest
swagger.conf.base-package=com.icare.bracelet
swagger.conf.title=我的手环bracelet rest接口
swagger.conf.desc=api地址http://${host}/
swagger.conf.service-url=http://${host}/
swagger.conf.version=1.0

但是这个配置要注意一下，汉字要转成ASCII码，不能直接写汉字，否则页面解码会乱码，写成下面这样：

# swagger config
swagger.conf.host=${host}:${server.port}
swagger.conf.group-name=bracelet-rest
swagger.conf.base-package=com.icare.bracelet
swagger.conf.title=\u6211\u7684\u624b\u73afbracelet rest\u63a5\u53e3
swagger.conf.desc=api\u5730\u5740http://${host}/
swagger.conf.service-url=http://${host}/
swagger.conf.version=1.0

4、启动微服务，然后访问http://127.0.0.1:10200/swagger-ui.html即可看到API界面！

展开来看

这样对于后端开发调试或者前后端联调都很方便，它能够解析出接口url和入参类型json，出参类型json,直接在web页面调用。

------------------------

功能增强：

上面只是提供了基本功能，但是还是不够完善，比如，前端人员或者其他调用方，看到这个很难知道接口的功能作用，接口参数的意义，那么下面可以通过注解来，增强此功能：

5、rest层代码如下

@Slf4j
@RestController
@CrossOrigin
@RequestMapping("/v1/remote/control/")
@Api(tags = {"远程模拟请求服务rest层"})
public class RemoteControlRest {

    @PostMapping("doPingRest")
    @ApiOperation("URL连通性测试接口")
    public ResponseResult<String> doPing(@ApiParam("请求参数") @RequestBody PingDto pingDto){
        return remoteControlService.ping(pingDto);
    }

}

分别在类上方加注解@Api(tags = {"远程模拟请求服务rest层"})，

在方法上加注解@APiOperation("URL连通性测试接口")，

在入参括号里加注解@ApiParam("请求参数")

在入参出参对象里面加注解

比如，在PingDto类里加注解

@Data
@ApiModel("Ping测试入参体")
public class PingDto {

    @ApiModelProperty("待测试URL")
    private String url;

    @ApiModelProperty("接口类型POST、GET等")
    private String method;

    @ApiModelProperty("接口参数map集合")
    private Map<String,Object> urlParams;

    @ApiModelProperty("参数体")
    private Object bodyParams;

    @ApiModelProperty("请求头参数map集合")
    private Map<String,String> headers;

    @ApiModelProperty("Cookie参数map集合")
    private Map<String ,Object> cookies;
}

出参对象同样的道理

@ApiModel("响应体")
public class ResponseResult<T> implements Serializable {

    private static final long serialVersionUID = -2391938914864875717L;

    @ApiModelProperty("响应是否成功")
    private boolean success;

    @ApiModelProperty("返回数据体")
    private T data;

    @ApiModelProperty("响应编码")
    private String code;

    @ApiModelProperty("响应信息")
    private String message;

    @ApiModelProperty("响应信息详情")
    private String detailMessage;

    @ApiModelProperty("请求URL")
    private String url;

加上这些注解后，在api上看起来就更加详细了

完成这些，需要配置的东西已经完成了，下面进行连接测试

6、web页面进行接口测试

填写参数，点击【Try it out!】，响应结果

OK,Over!