微服务集成Swagger2【SpringCloud，SpringBoot】

秒速五厘米 2023-07-14 10:56 147阅读 0赞

> 文章优先发表在个人博客上面，后续更新可能忘记同步到CSDN，给你带来不便抱歉。  
> 个人博客本篇文章地址：[https://www.xdx97.com/article/688418128744415232][https_www.xdx97.com_article_688418128744415232]

> 因为微服务是由多个服务构成如果每个服务的接口去开启新的页面这将十分难受。  
> 下面教大家怎么把多个服务的API接口集成到一个页面中去。

### 文章目录 ###

*   *  1、效果演示
     *  2、代码部分
     *   *   *  2-1：导入依赖包
             *  2-2：配置yml文件
             *  2-3：配置服务的Swagger2Config
             *  2-3：配置zuul的SwaggerConfig
     *  3、具体应用
     *   *   *  3-1：首先在controller配置注解@Api
             *  3-2、get请求参数配置
             *  3-3、post请求参数配置
             *   *   *  3-3-1：先配置实体
                     *  3-3-2：配置接口
     *  4、其它
     *   *   *  4-1：全部注解可以看这里
             *  4-2：常见错误
             *  4-3：代码是开源的，地址如下：

## 1、效果演示 ##

![在这里插入图片描述][20200314165538160.gif]

## 2、代码部分 ##

#### 2-1：导入依赖包 ####

<dependency>
         <groupId>com.spring4all</groupId>
         <artifactId>swagger-spring-boot-starter</artifactId>
         <version>1.7.0.RELEASE</version>
    </dependency>

需要在zuul 、和你的服务里面都加入依赖。我这里有两个服务**用户**、**工具**所以我们需要添加三次。（你按照具体服务添加即可）

**注：这个依赖可能会和SpringBoot版本冲突，1.7.0和boot2.0可以，但是boot2.0和1.9.0就报错，具体看你的版本。**

#### 2-2：配置yml文件 ####

**需要在你的服务里面配置下面的代码，你配置你的controller位置就好了**

#swagger扫包
    swagger:
      base-package: com.xdx97.framework.controller

#### 2-3：配置服务的Swagger2Config ####

这两个配置也是在你具体的服务里面配置的

import org.springframework.context.annotation.Bean;
    import org.springframework.context.annotation.Configuration;
    import springfox.documentation.builders.ApiInfoBuilder;
    import springfox.documentation.service.ApiInfo;
    import springfox.documentation.spi.DocumentationType;
    import springfox.documentation.spring.web.plugins.Docket;
    import springfox.documentation.swagger2.annotations.EnableSwagger2;
    
    @Configuration
    @EnableSwagger2
    public class Swagger2Config { 
    
        public static final String VERSION = "1.0.0";
    
        @Bean
        public Docket createRestApi() { 
            return new Docket(DocumentationType.SWAGGER_2)
                    .apiInfo(apiInfo());
        }
    
        private ApiInfo apiInfo() { 
            return new ApiInfoBuilder()
                    //设置文档的标题
                    .title("工具相关服务")
                    // 设置文档的描述
                    .description("工具相关服务 API 接口文档")
                    // 设置文档的版本信息-> 1.0.0 Version information
                    .version(VERSION)
                    // 设置文档的License信息->1.3 License information
                    .build();
        }
    }

#### 2-3：配置zuul的SwaggerConfig ####

import org.springframework.context.annotation.Primary;
    import org.springframework.stereotype.Component;
    import springfox.documentation.swagger.web.SwaggerResource;
    import springfox.documentation.swagger.web.SwaggerResourcesProvider;
    
    import java.util.ArrayList;
    import java.util.List;
    
    @Component
    @Primary
    class SwaggerConfig implements SwaggerResourcesProvider { 
        @Override
        public List<SwaggerResource> get() { 
            List resources = new ArrayList<>();
            resources.add(swaggerResource("用户服务", "/xdx/myuser/v2/api-docs", "2.0"));
            resources.add(swaggerResource("工具服务", "/xdx/mytools/v2/api-docs", "2.0"));
            return resources;
        }
    
        private SwaggerResource swaggerResource(String name, String location, String version) { 
            SwaggerResource swaggerResource = new SwaggerResource();
            swaggerResource.setName(name);
            swaggerResource.setLocation(location);
            swaggerResource.setSwaggerVersion(version);
            return swaggerResource;
        }
    }

这里说一下上面代码中间的地址怎么配置。

我访问服务的接口是这样的：http://myzuul.com:9527/xdx/myuser/authority/menu/list

**/xdx** 是我的访问前缀，如果你没有你可以不要。

**/myuser** 是我的服务别名，你换成你的就好了。

假如说你的前缀是 **/xxx**, 服务名是 **/yyy**，那么你的地址就是： /xxx/yyy/v2/api-docs

## 3、具体应用 ##

**具体应用和SpringBoot是一样的，如果你会下面就可以不看了。**

#### 3-1：首先在controller配置注解@Api ####

@Api(tags = "用户相关接口", description = "提供用户相关的 Rest API")

![在这里插入图片描述][watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L1RvbXdpbGRib2Fy_size_16_color_FFFFFF_t_70]

#### 3-2、get请求参数配置 ####

![在这里插入图片描述][watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L1RvbXdpbGRib2Fy_size_16_color_FFFFFF_t_70 1]

@ApiOperation(value = "登录", notes = "创建人- 小道仙")
    @ApiParam(value = "用户名", required = true)

#### 3-3、post请求参数配置 ####

###### 3-3-1：先配置实体 ######

![在这里插入图片描述][watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L1RvbXdpbGRib2Fy_size_16_color_FFFFFF_t_70 2]

@ApiModel("用户新增更新dto")
    @ApiModelProperty("用户id")

###### 3-3-2：配置接口 ######

![在这里插入图片描述][watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L1RvbXdpbGRib2Fy_size_16_color_FFFFFF_t_70 3]

## 4、其它 ##

#### 4-1：全部注解可以看这里 ####

[https://www.leeyom.top/2017/09/25/tech-swagger-annotation/][https_www.leeyom.top_2017_09_25_tech-swagger-annotation]  
[https://www.ibm.com/developerworks/cn/java/j-using-swagger-in-a-spring-boot-project/index.html][https_www.ibm.com_developerworks_cn_java_j-using-swagger-in-a-spring-boot-project_index.html]

#### 4-2：常见错误 ####

[https://www.cnblogs.com/xiebq/p/9508848.html][https_www.cnblogs.com_xiebq_p_9508848.html]

#### 4-3：代码是开源的，地址如下： ####

[https://github.com/xdxTao/xdx-framework-SpringCloud][https_github.com_xdxTao_xdx-framework-SpringCloud]

[https_www.xdx97.com_article_688418128744415232]: https://www.xdx97.com/article/688418128744415232
[20200314165538160.gif]: /images/20230529/0dc880717e474e698255321dfeefd05d.png
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L1RvbXdpbGRib2Fy_size_16_color_FFFFFF_t_70]: /images/20230529/1e9d5b73df244ac099d52a9794cc7266.png
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L1RvbXdpbGRib2Fy_size_16_color_FFFFFF_t_70 1]: /images/20230529/5c49f27e6cb44bb4aca57c80a023e177.png
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L1RvbXdpbGRib2Fy_size_16_color_FFFFFF_t_70 2]: /images/20230529/4484db231fbf422f97a9d14938f16a65.png
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L1RvbXdpbGRib2Fy_size_16_color_FFFFFF_t_70 3]: /images/20230529/13a9cbcba696456cae97c6f59421cd12.png
[https_www.leeyom.top_2017_09_25_tech-swagger-annotation]: https://www.leeyom.top/2017/09/25/tech-swagger-annotation/
[https_www.ibm.com_developerworks_cn_java_j-using-swagger-in-a-spring-boot-project_index.html]: https://www.ibm.com/developerworks/cn/java/j-using-swagger-in-a-spring-boot-project/index.html
[https_www.cnblogs.com_xiebq_p_9508848.html]: https://www.cnblogs.com/xiebq/p/9508848.html
[https_github.com_xdxTao_xdx-framework-SpringCloud]: https://github.com/xdxTao/xdx-framework-SpringCloud