SpringBoot gradle项目集成swagger

你的名字 2022-03-19 04:40 645阅读 0赞

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

详细参考官方文档