【java_wxid项目】【第十二章】【Swagger集成】

原创已于 2022-12-05 21:23:44 修改 · 651 阅读

2 ·

CC 4.0 BY-SA版权

##############阁下如果是抄袭，爬取文章作恶或误导他人的开发者,请阅读中国现行法律的相关处罚条例再动手，转载之前最好先验证#############

文章标签：

#java #spring cloud #微服务

于 2022-09-24 11:01:37 首次发布

java_wxid项目同时被 2 个专栏收录

19 篇文章

订阅专栏

接口文档

3 篇文章

订阅专栏

主项目链接：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                                                            // 演示模块
│     └── 模块名称：apache-mybatis-demo模块                            //Apache Mybatis集成（已实现并有博文总结）
│     └── 模块名称：apache-shardingsphere-demo模块                     //Apache ShardingSphere集成（已实现并有博文总结）
│     └── 模块名称：design-demo模块                                    //设计模式实战落地（已实现并有博文总结）
│     └── 模块名称：elasticsearch-demo模块                             //ElasticSearch集成（已实现并有博文总结）
│     └── 模块名称：mongodb-demo模块                                   //MongoDB集成（已实现并有博文总结）
│     └── 模块名称：redis-demo模块                                     //Redis集成（已实现并有博文总结）
│     └── 模块名称：spring-boot-demo模块                               //Spring Boot快速构建应用（已实现并有博文总结）
│     └── 模块名称：spring-cloud-alibaba-nacos-demo模块                //Spring Cloud Alibaba Nacos集成（已实现并有博文总结）
│     └── 模块名称：spring-cloud-alibaba-seata-demo模块                //Spring Cloud Alibaba Seata集成（已实现并有博文总结）
│     └── 模块名称：spring-cloud-alibaba-sentinel-demo模块             //Spring Cloud Alibaba Sentinel集成（已实现并有博文总结）
│     └── 模块名称：spring-cloud-gateway-demo模块                      //Spring Cloud Gateway集成（已实现并有博文总结）
│     └── 模块名称：spring-cloud-hystrix-demo模块                      //Spring Cloud Hystrix集成（已实现并有博文总结）
│     └── 模块名称：spring-cloud-open-feign-demo模块                   //Spring Cloud Open Feign集成（已实现并有博文总结）
│     └── 模块名称：spring-cloud-ribbon-demo模块                       //Spring Cloud Ribbon集成（已实现并有博文总结）
│     └── 模块名称：spring-cloud-security-oauth2-demo模块              //Spring Cloud Security Oauth2集成（已实现并有博文总结）
│     └── 模块名称：spring-cloud-security-oauth2-sso-client-demo模块   //Spring Cloud Security Oauth2集成（已实现并有博文总结）
│     └── 模块名称：spring-cloud-skywalking-demo模块                   //Spring Cloud Skywalking集成（已实现并有博文总结）
│     └── 模块名称：spring-cloud-stream-demo模块                       //Spring Cloud Stream集成（已实现并有博文总结）
│     └── 模块名称：swagger-demo模块                                   //springfox-swagger2集成（已实现并有博文总结）
│     └── 模块名称：xxl-job模块                                        //xxl-job集成（已实现并有博文总结）
│     └── 模块名称：apache-spark-demo模块                              //Apache Spark集成
│     └── 模块名称：etl-hdfs-hive-hbase-demo模块                       //ETL、HDFS、Hive、Hbase集成
│     └── 模块名称：ddd-mode-demo模块                                  //DDD领域设计
│     └── 模块名称：netty-demo模块                                     //Netty集成
│     └── 模块名称：vue-demo模块                                       //前端vue集成
├── document                                                        // 文档
│     └── JavaKnowledgeDocument                                     //java知识点
│           └── java基础知识点.md                     
│           └── mq知识点.md
│           └── mysql知识点.md
│           └── redis知识点.md
│           └── springcould知识点.md
│           └── spring知识点.md
│     └── FounderDocument                                           //创始人
│           └── 创始人.md

系列文章：快速集成各种微服务相关的技术，帮助大家可以快速集成到自己的项目中，节约开发时间。
提示：系列文章还未全部完成，后续的文章，会慢慢补充进去的。

文章目录

创建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;
    }
}