Java中让Swagger产出更加符合我们诉求的描述文档,按需决定显示或者隐 ...
发布网友
共1个回答
热心网友
更改接口文档总标题与描述
默认情况下，Swagger 的界面总标题与描述内容为通用值，这可能导致用户难以辨识文档所属项目、系统、版本以及维护团队等信息。为了提高文档的专业性与可读性，可在代码中根据需要自定义相关字段，如项目名称、版本号、团队信息等。自定义后，文档的名称与描述将更加清晰且专业。
通过手动调整，可以灵活控制需要包含在文档中的接口内容与请求响应体中的字段信息。并非所有系统接口都需要在文档中展示，如状态监控接口等。Swagger 提供了多种方式支持按需显示或隐藏接口内容。
针对单个接口进行隐藏，可在接口方法上方使用 @ApiOperation 注解，并指定 hidden = true。调整后，重启进程查看 Swagger 界面，发现该接口已被隐藏。
若需隐藏整个 Controller 类中的所有接口，可在 Controller 类上添加 @ApiIgnore 注解。改动后，重启进程并打开 Swagger 界面，发现整个 Controller 类的接口均未显示。
为了优化项目中依赖的三方 jar 包接口的展示，可通过给定的 basePackage 与 paths 组合控制，仅显示指定 package 目录下的 Controller 接口。这能确保接口文档只包含自定义接口，避免出现不确定内容。
在项目开发中，为减少编码量，可能会使用同一个对象处理内部逻辑与外部交互。通过在指定字段上添加 @ApiModelProperty 注解并设置 hidden = true，可以隐藏响应中不愿暴露的属性，避免给调用方带来困惑。
考虑生产环境的安全性，可使用 SpringBoot 的环境配置功能某些环境（如生产环境）不允许访问 Swagger。借助 @Profile 注解，可以在启动时根据环境变量决定是否加载 Swagger 配置。
为了提升使用体验，可以使用开源框架 knife4j 来更换 Swagger 的界面风格。knife4j 提供了更美观且易于操作的文档界面，可显著提升接口文档的用户体验。
总结，通过自定义标题与描述、灵活控制接口内容显示与隐藏、优化三方 jar 包接口展示、隐藏不需暴露的属性以及通过环境配置访问，可以实现更符合需求的 Swagger 接口文档。
