Swagger集成
Posted java_wxid
tags:
篇首语：本文由小常识网(cha138.com)小编为大家整理，主要介绍了Swagger集成相关的知识，希望对你有一定的参考价值。
主项目链接：https://gitee.com/java_wxid/java_wxid
项目架构及博文总结：
- 点击：【使用Spring Boot快速构建应用】
- 点击：【使用Spring Cloud Open Feign基于动态代理动态构造请求实现与其他系统进行交互】
- 点击：【使用Spring Cloud Hystrix实现服务容错、熔断、降级、监控】
- 点击：【使用Spring Cloud Ribbon以库的方式集成到服务的消费方实现客户端负载均衡】
- 点击：【使用Spring Cloud Gateway作为API网关服务进行请求拦截、服务分发、降级、限流】
- 点击：【使用Spring Cloud Security Oauth2作为微服务统一认证中心实现用户认证和授权访问】
- 点击：【使用Spring Cloud Stream作为消息驱动用于动态的切换中间件】
- 点击：【使用Spring Cloud Skywalking基于字节码注入通过探针方式进行链路追踪、分布式追踪、性能指标分析、应用和服务依赖分析
- 点击：【使用Spring Cloud Alibaba Nacos实现服务注册/发现/续约/剔除/下线、心跳检测、服务配置管理、基于长轮训机制实现配置动态变更】
- 点击：【使用Spring Cloud Alibaba Seata作为对项目代码无入侵的分布式事务解决方案】
- 点击：【使用Spring Cloud Alibaba Sentinel实现高可用流量防护】
- 点击：【使用Apache ShardingSphere作为关系型数据库中间件实现分库分表、读写分离】
- 点击：【使用Apache Mybatis作为持久层框架用于定制化SQL、存储过程以及高级映射】
- 点击：【使用Redis作为高性能分布式缓存数据库】
- 点击：【使用ElasticSearch全文搜索】
- 点击：【使用MongoDB非关系型数据库】
- 点击：【使用xxl-job作为分布式任务调度平台】
- 点击：【使用Elasticsearch + Logstash + Kibana作为日志收集系统】
- 点击：【使用Apifox作为API文档、API调试、API Mock、API自动化测试】
- 点击：【使用Apache Spark作为基于内存计算的大数据分析引擎用于批处理、交互式查询】
- 点击：【使用ETL工具将数据源抽取到HDFS作为高可靠、高吞吐量的分布式文件系统存储，通过Hive清洗、处理和计算原始数据，Hive清洗处理后的结果，将存入Hbase，海量数据随机查询场景从HBase查询数据】
- 点击：【使用领域驱动DDD设计和设计模式进行开发】
- 点击：【使用Netty基于Java NIO封装的高性能的网络通信框架】
- 点击：【使用k8s、docker、docker-compose、宝塔面板进行环境搭建和部署】
- 点击：【使用Vue渐进式javascript框架作为适用场景丰富的Web前端框架】
- 点击：【分享人才筛选、工作分配、高效办公、项目推动等团队管理经验】
项目模块：
前期规划，实现部分
java_wxid
├── demo // 演示模块
│ └── 模块名称：spring-boot-demo模块 //Spring Boot快速构建应用（已实现并有博文总结）
│ └── 模块名称：spring-cloud-alibaba-nacos-demo模块 //Spring Cloud Alibaba Nacos集成（已实现并有博文总结）
│ └── 模块名称：spring-cloud-open-feign-demo模块 //Spring Cloud Open Feign集成（已实现并有博文总结）
│ └── 模块名称：spring-cloud-hystrix-demo模块 //Spring Cloud Hystrix集成（已实现并有博文总结）
│ └── 模块名称：spring-cloud-ribbon-demo模块 //Spring Cloud Ribbon集成（已实现并有博文总结）
│ └── 模块名称：spring-cloud-gateway-demo模块 //Spring Cloud Gateway集成（已实现并有博文总结）
│ └── 模块名称：spring-cloud-security-oauth2-demo模块 //Spring Cloud Security Oauth2集成（已实现并有博文总结）
│ └── 模块名称：spring-cloud-stream-demo模块 //Spring Cloud Stream集成(框架已搭建，待校验，待博文总结)
│ └── 模块名称：spring-cloud-skywalking-demo模块 //Spring Cloud Skywalking集成(框架已搭建，待校验，待博文总结)
│ └── 模块名称：spring-cloud-alibaba-seata-demo模块 //Spring Cloud Alibaba Seata集成（已实现并有博文总结）
│ └── 模块名称：spring-cloud-alibaba-sentinel-demo模块 //Spring Cloud Alibaba Sentinel集成(框架已搭建，待校验，待博文总结)
│ └── 模块名称：apache-shardingsphere-demo模块 //Apache ShardingSphere集成（已实现并有博文总结）
│ └── 模块名称：apache-mybatis-demo模块 //Apache Mybatis集成（已实现并有博文总结）
│ └── 模块名称：redis-demo模块 //Redis集成（已实现并有博文总结）
│ └── 模块名称：elasticsearch-demo模块 //ElasticSearch集成(框架已搭建，待校验，待博文总结)
│ └── 模块名称：mongodb-demo模块 //MongoDB集成（已实现并有博文总结）
│ └── 模块名称：xxl-job-demo模块 //xxl-job集成(框架已搭建，待校验，待博文总结)
│ └── 模块名称：apache-spark-demo模块 //Apache Spark集成
│ └── 模块名称：etl-hdfs-hive-hbase-demo模块 //ETL、HDFS、Hive、Hbase集成
│ └── 模块名称：ddd-design-mode-demo模块 //DDD、设计模式集成
│ └── 模块名称：netty-demo模块 //Netty集成
│ └── 模块名称：vue-demo模块 //前端vue集成
├── document // 文档
│ └── README.ch.md //中文文档
│ └── README.en.md //英文文档
系列文章：前期主要以demo项目为主，快速集成各种微服务相关的技术，帮助大家可以快速集成到自己的项目中，节约开发时间。后期则会以企业实战项目为主，致力于解决高并发、高可用、高性能、高可靠、海量数据等疑难问题，同时记录工作中遇到的技术难点、有技术亮点，项目会结合博客、视频辅助讲解，帮助大家查询是否遇到过同类型的问题。
提示：系列文章还未全部完成，后续的文章，会慢慢补充进去的。
文章目录
创建swagger-demo项目
项目代码：https://gitee.com/java_wxid/java_wxid/tree/master/demo/swagger-demo
项目结构如下（示例）：
修改pom.xml
代码如下（示例）：
<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
<modelVersion>4.0.0</modelVersion>
<groupId>com.example</groupId>
<artifactId>swagger-demo</artifactId>
<version>0.0.1-SNAPSHOT</version>
<name>swagger-demo</name>
<description>Demo project for Spring Boot</description>
<!-- 属性配置-->
<properties>
<project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
<project.reporting.outputEncoding>UTF-8</project.reporting.outputEncoding>
<java.version>1.8</java.version>
<!--引入 Spring Boot、Spring Cloud、Spring Cloud Alibaba 三者 BOM 文件，进行依赖版本的管理，防止不兼容。
在 https://dwz.cn/mcLIfNKt 文章中，Spring Cloud Alibaba 开发团队推荐了三者的依赖关系-->
<spring.boot.version>2.3.12.RELEASE</spring.boot.version>
<spring.cloud.version>Hoxton.SR12</spring.cloud.version>
<spring.cloud.alibaba.version>2.2.7.RELEASE</spring.cloud.alibaba.version>
<swagger2.version>2.9.2</swagger2.version>
</properties>
<dependencies>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter</artifactId>
</dependency>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-test</artifactId>
<scope>test</scope>
<exclusions>
<exclusion>
<groupId>org.junit.vintage</groupId>
<artifactId>junit-vintage-engine</artifactId>
</exclusion>
</exclusions>
</dependency>
<!-- 代表web模块，在这个模块中含了许多JAR包，有spring相关的jar，内置tomcat服务器，jackson等，这些web项目中常用的的功能都会自动引入-->
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-web</artifactId>
</dependency>
<!-- swagger-->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>$swagger2.version</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>$swagger2.version</version>
</dependency>
<!-- 开发热启动:在开发过程中，由于每次修改完项目中的类都需要重启服务才能看到运行的结果，对于开发调试很不友好，浪费时间，引入devtools工具可以快速启动项目 -->
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-devtools</artifactId>
<optional>true</optional>
</dependency>
</dependencies>
<!--
引入 Spring Boot、Spring Cloud、Spring Cloud Alibaba 三者 BOM 文件，进行依赖版本的管理，防止不兼容。
在 https://dwz.cn/mcLIfNKt 文章中，Spring Cloud Alibaba 开发团队推荐了三者的依赖关系
-->
<dependencyManagement>
<dependencies>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-parent</artifactId>
<version>$spring.boot.version</version>
<type>pom</type>
<scope>import</scope>
</dependency>
<dependency>
<groupId>org.springframework.cloud</groupId>
<artifactId>spring-cloud-dependencies</artifactId>
<version>$spring.cloud.version</version>
<type>pom</type>
<scope>import</scope>
</dependency>
<dependency>
<groupId>com.alibaba.cloud</groupId>
<artifactId>spring-cloud-alibaba-dependencies</artifactId>
<version>$spring.cloud.alibaba.version</version>
<type>pom</type>
<scope>import</scope>
</dependency>
</dependencies>
</dependencyManagement>
<build>
<plugins>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-compiler-plugin</artifactId>
<version>3.8.1</version>
<configuration>
<source>1.8</source>
<target>1.8</target>
<encoding>UTF-8</encoding>
</configuration>
</plugin>
<plugin>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-maven-plugin</artifactId>
<version>2.3.7.RELEASE</version>
<configuration>
<mainClass>com.example.swaggerdemo.SwaggerDemoApplication</mainClass>
</configuration>
<executions>
<execution>
<id>repackage</id>
<goals>
<goal>repackage</goal>
</goals>
</execution>
</executions>
</plugin>
</plugins>
</build>
</project>
创建Swagger2Config
代码如下（示例）：
package com.example.swaggerdemo.config;
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.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
/**
* 访问地址：http://localhost:8080/swagger-ui.html
*/
@Configuration
@EnableSwagger2
public class Swagger2Config
@Bean
public Docket createRestApi()
Contact contact = new Contact("java_wxid","","java_wxid@aliyun.com");
ApiInfo apiInfo=new ApiInfoBuilder()
.title("swagger接口")
.description("案例相关接口描述")
.version("1.0.0")
.contact(contact)
.build();
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo)
.select()
.apis(RequestHandlerSelectors.basePackage("com.example.swaggerdemo.controller"))
.paths(PathSelectors.any())
.build();
创建UserController
代码如下（示例）：
package com.example.swaggerdemo.controller;
import com.example.swaggerdemo.model.UserInfoVo;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import io.swagger.annotations.ApiParam;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;
@Api("用户管理")
@RestController
@RequestMapping("/user")
public class UserController
@ApiOperation(value="接口说明:获取用户信息",httpMethod="GET",notes="接口发布说明")
@GetMapping("/getUserInfo")
public UserInfoVo getUserInfo(@ApiParam(required = true, name = "用户id", value = "userId") String userId)
UserInfoVo userInfoVo = new UserInfoVo();
userInfoVo.setUserId(userId);
return userInfoVo;
创建UserInfoVo
代码如下（示例）：
package com.example.swaggerdemo.model;
import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
@ApiModel(value = "用户信息展示给页面的实体类",description ="用户实体类的注释")
public class UserInfoVo
@ApiModelProperty(value = "用户Id")
private String userId;
public String getUserId()
return userId;
public void setUserId(String userId)
this.userId = userId;
校验Swagger是否正常工作
启动项目
如下图（示例）：
访问接口http://localhost:8080/swagger-ui.html
以上是关于Swagger集成的主要内容，如果未能解决你的问题，请参考以下文章