Skip to content

Conversation

@acpplife
Copy link

Summary

This PR adds a configurable operationId generation strategy to allow users to choose different formats for
operationId in the generated OpenAPI documentation.

Motivation

After commit b279aa6, the operationId was changed from methodId (e.g., athena-machine-getGuarderToken-POST)
to method name only (e.g., openRoomAndUploadNextSection). This PR provides a configuration option to support
multiple strategies.

Changes

  • Add OperationIdStrategyEnum with three strategies:
    • METHOD_NAME: Use the method name only (default, with duplicate handling)
    • METHOD_ID: Use the methodId (MD5 hash)
    • PATH_METHOD_HTTP: Use path + method name + HTTP method type
  • Add operationIdStrategy configuration field in ApiConfig
  • Update OpenApiBuilder to implement the strategy logic
  • Maintain backward compatibility with METHOD_NAME as default

Usage Example

In smart-doc.json:

{
  "operationIdStrategy": "PATH_METHOD_HTTP"
}

Examples

- METHOD_NAME: getUserInfo or getUserInfo_1 for duplicates
- METHOD_ID: user-controller-getUserInfo-1-a1b2c3d4e5f6
- PATH_METHOD_HTTP: api-users-updateProfile-POST

- Add OperationIdStrategyEnum with three strategies: METHOD_NAME, METHOD_ID, PATH_METHOD_HTTP
- Add operationIdStrategy configuration option in ApiConfig
- Update OpenApiBuilder to support multiple operationId generation patterns
- Maintain backward compatibility with METHOD_NAME as default

This allows users to choose different operationId formats in smart-doc.json configuration file.
@github-actions
Copy link

@acpplife

🔍 Before proceeding, please review the contribution guidelines

This includes requirements for:

  • ✅ Commit message format (Angular Convention. feat, fix, etc.)
  • 🧹 Code style (execute mvn spring-javaformat:apply)
  • 📄 Documentation updates (if config changes)
  • 💡 Example code submission (for new features)

Thanks for your PR. 🙏
Please check again for your PR changes whether they contain any usage configuration change, such as Add new configuration or Change default value of configuration.
If so, please add or update documents (Markdown format) in the docs/ directory of the repository smart-doc-group/smart-doc-group.github.io.

In addition, if you have added new features, please provide example code in the repository smart-doc-group/smart-doc-example-cn. This will help other users understand how to use the new features.

Code Style Reminder:
The code should use the Spring code style. Please format your code using the command mvn spring-javaformat:apply. You can also install the Spring Java Format plugin for convenience.


🔍 提交前请务必完成以下检查

需特别注意:

  • ✅ 提交信息格式 (feat, fix 等类型)
  • 🧹 代码风格(执行 mvn spring-javaformat:apply
  • 📄 文档更新(配置变更需同步更新 docs)
  • 💡 示例代码(新功能需提供示例)

感谢您提交的PR。 🙏
请再次查看您的PR内容,确认是否包含任何使用方式或配置参数的变更,如:新增配置参数修改默认配置等操作。
如果是,请确保在提交之前,在仓库smart-doc-group/smart-doc-group.github.io中的docs/目录下添加或更新文档(Markdown格式)。

另外,如果您添加了新功能,请在仓库smart-doc-group/smart-doc-example-cn中提供示例代码。这将帮助其他用户了解如何使用新功能。

代码风格提示:
请使用 Spring 代码风格。您可以通过命令 mvn spring-javaformat:apply 格式化代码。为了方便操作,您还可以安装 Spring Java Format 插件。

@linwumingshi
Copy link
Collaborator

Hi @acpplife thanks for your contribution!

Before we can review and merge this PR, could you please follow the guidelines outlined in the CONTRIBUTING.md file? Specifically:

Once these changes are made, let us know and we'll continue with the review.

Looking forward to your updates!


你好 @acpplife ,感谢你的贡献!

在我们能够继续审查和合并这个 PR 之前,请你按照项目中的 CONTRIBUTING.md 文件中的指南进行调整。具体包括:

修改完成后欢迎继续更新此 PR,我们会继续跟进审核。

期待你的更新!

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants