SpringBoot gradle项目集成swagger

SpringBoot gradle项目集成swagger

1.简介以及原理

简介: Java库的Springfox套件全部是关于使用spring项目编写的JSON API自动生成机器和人类可读的规范。Springfox的工作原理是在运行时检查应用程序,以便根据弹簧配置,类结构和各种编译时间的Java注释来推断API语义。 Swagger是一个规范和完整的框架,用于生成、描述、调用和可视化RESTful 风格的 Web 服务。总体目标是使客户端和文件系统作为服务器以同样的速度来更新。文件的方法,参数和模型紧密集成到服务器端的代码,允许API来始终保持同步。Swagger 让部署管理和使用功能强大的API从未如此简单。 原理: 后台:后端部分与Java集成,后最终会产生一个json文件。 前台:前台部分就是html、css、js文件,js利用后台产生的json文件构造api; 优点: 1.所有接口方法可以动态的生成API文档,减少前端、测试等人员想开发询问接口入参、减少开发编写API文档的苦逼; 2.其次swagger默认生成的原始文件是JSON文件,前端在开发的时候比较喜欢用RAP进行服务mock,RAP也支持JSON文件导入,因此可以基于swagger生成的JSON文件,写个小程序自动改造成RAP支持的JSON格式,从而提高整个项目开发及测试效率 Swagger UI gitHub地址:https://github.com/swagger-api/swagger-ui

2.现有的项目集成:*重点内容*

集成前的目录如下这里写图片描述

集成步骤:

2.1第一步,在GitHub上下载SwaggerUI项目,将dist下所有内容拷贝到本地项目server-api/webapp下面,结果目录如下图所示:这里写图片描述拷贝目录如图:这里写图片描述修改index.html文件将 url = “http://petstore.swagger.io/v2/swagger.json“; 改为url=”/v2/api-docs”;这里写图片描述

2.2第二步,添加gradle依赖

*
compile('io.springfox:springfox-swagger2:2.8.0')
compile('io.springfox:springfox-swagger-ui:2.8.0')
compile 'io.swagger:swagger-jersey2-jaxrs:1.5.8'
compile('com.mangofactory:swagger-springmvc:1.0.2')
compile('com.mangofactory:swagger-models:1.0.2')
compile('com.wordnik:swagger-annotations:1.3.11')*

目前最新版本是2.8.0(2018.1.26) Springfox Swagger2 官网:https://mvnrepository.com/artifact/io.springfox/springfox-swagger2 Springfox Swagger Ui官网:https://mvnrepository.com/artifact/io.springfox/springfox-swagger-ui

2.3第三步,Docket Spring Java配置

• 使用@EnableSwagger或@EnableSwagger2注释。 • 使用弹簧@Bean注释定义一个或多个Docket实例。 添加swagger配置文件SwaggerConfig.java 以及主入口文件添加注解:这里写图片描述贴上代码如下:
package com.example.demo18.config;

import org.assertj.core.util.Lists;
import org.springframework.context.annotation.Bean;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger.web.UiConfiguration;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

import java.util.HashSet;

@org.springframework.context.annotation.Configuration
@EnableSwagger2
public class SwaggerConfig {
    @Bean
    public Docket documentation(){
        return new Docket(DocumentationType.SWAGGER_2)
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.example.demo18"))
                .build()
                .protocols(new HashSet<String>(Lists.newArrayList("http")))
                .pathMapping("/")
                .apiInfo(apiInfo());
    }

    @Bean
    public UiConfiguration uiConfig(){
        return UiConfiguration.DEFAULT;
    }

    private ApiInfo apiInfo(){
        return new ApiInfoBuilder()
                .title("服务API")
                .description("服务端后台接口说明文档")
                .version("1.0")
                .build();
    }
}
主入口文件添加注解:@EnableSwagger2 用于启用Springfox Swagger 2这里写图片描述添加api接口Swagger2这里写图片描述贴上简单例子:
package com.example.demo18.swagger;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

@Configuration //让Spring来加载该类配置
@EnableSwagger2 //启用Swagger2
public class Swagger2 {
    @Bean
    public Docket MapperApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .groupName("MapperApi接口")
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.example.demo18.Mapper"))
                .paths(PathSelectors.any()).build();
    }
    @Bean
    public Docket PersonApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .groupName("PersonApi接口")
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.example.demo18.Person"))
                .paths(PathSelectors.any()).build();
    }
    @Bean
    public Docket ServiceApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .groupName("Service接口")
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.example.demo18.Service"))
                .paths(PathSelectors.any()).build();
    }
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("APi接口")
                .description("增删改查服务")
                .termsOfServiceUrl("http://www.baidu.com")
                .version("1.0").build();
    }
}
运行效果:这里写图片描述

2.4第四步,在Controller添加注解

以下是示例:只加入了两行注解:这里写图片描述关于注解,参考官方文档: https://springfox.github.io/springfox/javadoc/current/ 3演示效果: 打开链接:http://localhost:8080/swagger/index.html 显示效果如图:这里写图片描述打开链接:http://localhost:8080/swagger-ui.html这里写图片描述

4.参考文档:

Springfox参考文档: 教程参考网址:https://testerhome.com/topics/7304 详细参考官方文档