给Swagger换上新的皮肤

一： Swagger介绍

1. 随着现在微服务的发展和前后端分离的需要，现在接口文档尤其重要，在前后端分离的开发中，前后端联调一个好的接口文档特别重要，今天给大家分享一款前后端分离的接口文档神器，swagger，大家一定想swagger在工作中已经很熟悉了，有什么可介绍的，今天介绍的是在swagger上面做一一层优化的Swagger, 所以叫做给Swagger换一层新的皮肤

大多数项目使用swagger的配置如下（但是这种配置页面显示很不友好）

<!-- 配置 swagger ui-->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.8.0</version>
</dependency>
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.8.0</version>
</dependency>

访问接口地址:  http://localhost:port/swagger-ui.html  （如果你的项目名称加了前缀也需要加上）

是不是很难看呢

swagger 新皮肤在里的pom里面添加依赖如下依赖(原来上面的依赖不用添加了)

<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>knife4j-spring-boot-starter</artifactId>
    <!--在引用时请在maven中央仓库搜索最新版本号-->
    <version>2.0.4</version>
</dependency>

配置加载文件和原始的swagger一样，在项目里面新建一个config包(名称随便) 添加扫描swagger的类

@Configuration
@EnableSwagger2
public class Swagger2Config {

    @Bean
    public Docket createRestApi(){
        return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo()).select()
                // 你项目需要扫描注册接口包
                .apis(RequestHandlerSelectors.basePackage("com.zhuguang.zhou.swagger.controller"))
                .paths(PathSelectors.any()).build();
    }

    private ApiInfo apiInfo() {
       // 生成文当描述
        return new ApiInfoBuilder().title("swagger-ui").description("用户服务API文档")
                .contact(new Contact("zhoushisheng","","1358281371@qq.com")).version("1.0").build();
    }
}

访问接口地址: http://localhost:port/doc.html （如果你的项目名称加了前缀也需要加上）

左边为功能导航条，选择对应的模块和接口就可以进行调试了，调试如下

点击发送下面就会有返回对应的响应结果，是不是觉得高大上很多了

二： 下面来讲讲Swagger接口的配置注解

1.  @Api 标记在接口上面 描述该api的主要功能和他对应的在左边导航条的显示位置

2.  @Api(tags = "用户模块", position = 2)

@ApiOperation 对类里面单个接口的描述, value 和 notes  都是用来描述接口的主要功能

3. @ApiImplicitParams 对接口里面参数的描述  name 字段名称，dataType 数据类型，paramType 参数位置，

 required 是否必传 (里面还有很多参数这里就不做细化了胖友可以自行阅读) 

@ApiOperation(value = "根据客户标签发送消息",notes = "根据客户标签发送消息")
@ApiImplicitParams({
        @ApiImplicitParam(name = "title",value = "通知标题", dataType = "String", paramType="query", required = true),
        @ApiImplicitParam(name = "context",value = "通知内容", dataType = "String", paramType="query", required = true),
        @ApiImplicitParam(name = "tags",value = "客户标签", dataType = "List", paramType="body", required = true),
}

)

如果有登录权限拦截需要剔除下面的请求拦截才能显示页面信息

        paths.add("/swagger-ui.html/**");
        paths.add("/swagger-ui/**");
        paths.add("/swagger-resources/**");
        paths.add("/v2/api-docs/**");
        paths.add("/v3/api-docs/**");
        paths.add("/webjars/**");
        paths.add("/doc.html/**");
        paths.add("/favicon.ico");

关于其他的Swagger注解胖友可以自行阅读，当然优化后的Swagger可以在网关层将所有的网关下层模块一起集成起来，在这里面就不做介绍了，有兴趣的胖友可以自行研究，或是给我留言，笔者看到会及时回复，(这里提醒下胖友，在生产上面是不用将swagger的接口开放出来的所以需要做一个开关控制在生产上面不做Swagger的扫描，这个应该很简单吧，不会的胖友留言哈)

今天的分享就到这了 88