「初学者商城」- 接口 - 配置 swagger-ui 页面描述信息（优化）

小鱼儿 2023-02-19 10:26 43阅读 0赞

# 1. 前言 #

--------------------

正准备拉分支的，突然发现 swagger-ui 主页面的描述信息还是硬编码出来的，想着就是取一下对应工程版本号显示就可以了，然后就仅作为一次新的提交没必要打标签的，最后发现并不是想的那么简单…

# 2. 源码 #

--------------------

完整项目地址：[https://github.com/intomylife/osc-api][https_github.com_intomylife_osc-api]

v1.4.5 标签地址：[https://github.com/intomylife/osc-api/releases/tag/v1.4.5][https_github.com_intomylife_osc-api_releases_tag_v1.4.5]

v1.4.5 下载地址：[zip][]，[tar.gz][]

**注：对于标签的说明[「初学者商城」- 写在最前面 \#5.1][- _ _5.1]**

# 3. 接口 #

--------------------

**注：查看更改内容：[配置 swagger-ui 页面描述信息][swagger-ui]**

## 3.1 思路 ##

swagger-ui 页面要显示的版本信息其实就是服务工程的版本号，所以直接取到服务工程的版本号就可以了；而`Java`代码中无法直接获取到`pom.xml`文件中的属性，所以要先在配置文件中获取`pom.xml`中的属性值，然后再在`Java`代码中获取配置文件的配置信息，这样就能成功获取版本号，并显示在 swagger-ui 页面上

## 3.2 配置文件中获取 pom.xml 属性值 ##

一开始，想先在 commons 工程的配置文件中取到 pom.xml 的属性值，然后在 Swagger 自定义配置类`SwaggerConfig`中直接读取配置信息，最后发现获取到的却是`@project.name@`这样的字符串

### 3.2.1 占位符 @@ 和 $\{\} ###

两种占位符都可以在配置文件中获取到 pom.xml 的属性值，但是有硬性条件（需要满足其一）：

1.  添加过滤器
2.  引入`spring-boot-starter-parent`依赖

这就回到上面引发的问题了，为什么最后获取到的是`@project.name@`这样的字符串？因为 commons 工程一没有写过滤器，二没有引入`spring-boot-starter-parent`依赖

### 3.2.2 配置过滤器 ###

<resources>
            <resource>
                <directory>src/main/resources</directory>
                <filtering>true</filtering>
                <includes>
                    <include>**/*.properties</include>
                    <include>**/*.xml</include>
                </includes>
            </resource>
        </resources>

*  当配置过滤器后，在`system.properties`配置文件中，使用占位符`@@`或`${}`都可以成功获取到 pom.xml 的属性值了

## 3.3 在`Java`代码中获取配置文件的属性值 ##

使用`@Value("${}")`注解即可

## 3.4 其他 ##

其实最后是在各自需要`Swagger`的服务工程中单独做的配置，因为需要`Swagger`的服务工程都是引入过`spring-boot-starter-parent`依赖；这里主要是作为一个知识点记录一下

**服务工程单独的配置信息：**

# swagger-ui 页面描述信息
    osc:
      swagger:
        ## 应用名称
        name: @project.description@
        ## 版本号
        version: @project.version@

# 4. 验证 #

--------------------

## 4.1 接口 ##

1.  下载`v1.4.5`标签的代码或者对照本篇博客更改`v1.4.4`标签的代码
2.  打开`idea`右侧工具栏中的`Maven Projects`
3.  展开`osc-commons`\->`Lifecycle`
4.  先`clean`，再`install`
5.  结束后打开`osc-commons`工程，找到刚刚打包的`target -> classes -> config`目录中的`system.properties`文件，发现源码中的`@project.name@`被自动替换成了`osc-commons`，证明成功从 pom.xml 文件中获取到了对应的属性值
6.  这时再打开`osc-commons`工程的 pom.xml 文件，把`resources`节点注释掉（也就是`### 3.2.2`中配置的过滤器）
7.  重复步骤`2, 3, 4`
8.  结束后打开`osc-commons`工程，找到刚刚打包的`target -> classes -> config`目录中的`system.properties`文件，发现源码中的`@project.name@`依旧还是`@project.name@`
9.  当然，由于在各自需要`Swagger`的服务工程中都做了配置，所以 swagger-ui 主页面是可以成功分别显示对应服务工程的描述信息的（应用名称和版本号）
10. 启动所有工程，访问 [http://localhost:8000/swagger-ui.html][http_localhost_8000_swagger-ui.html] 查看效果

# 5. 结语 #

--------------------

这篇过后，专门拉了一个[分支][Link 1]，这个[分支][Link 1]作为完整的`SpringCloud`全家桶基础架构，由于部分组件已经闭源了，所以不得不拥抱`SpringCloudAlibaba`了；当然，仅仅是把闭源的部分组件更换。

接下来，先进入一小段时间的`SpringCloudAlibaba`学习之旅，巴适。

希望能够帮助到你

over

[https_github.com_intomylife_osc-api]: https://github.com/intomylife/osc-api
[https_github.com_intomylife_osc-api_releases_tag_v1.4.5]: https://github.com/intomylife/osc-api/releases/tag/v1.4.5
[zip]: https://github.com/intomylife/osc-api/archive/v1.4.5.zip
[tar.gz]: https://github.com/intomylife/osc-api/archive/v1.4.5.tar.gz
[- _ _5.1]: https://intomylife.blog.csdn.net/article/details/103745935
[swagger-ui]: https://github.com/intomylife/osc-api/commit/493cfda2cb1a9aa9a4803b220b6d77c98cb424c3
[http_localhost_8000_swagger-ui.html]: http://localhost:8000/swagger-ui.html
[Link 1]: https://github.com/intomylife/osc-api/tree/init-springcloud-all