Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

The documentation only outputs the specified interface. #519

Closed
Fioooooooo opened this issue Jun 16, 2023 · 5 comments
Closed

The documentation only outputs the specified interface. #519

Fioooooooo opened this issue Jun 16, 2023 · 5 comments
Milestone

Comments

@Fioooooooo
Copy link
Contributor

Fioooooooo commented Jun 16, 2023

Currently, the packageFilter parameter can only filter at the controller level. Is there a parameter that can support filtering at the individual interface level? If it's not supported at the moment, can I submit a PR (Pull Request) to add this functionality?

Due to ongoing project requirements, the number of interfaces is gradually increasing. We create a new smart-doc configuration file for each requirement and then set up a corresponding project on torna. This new project will only include the interfaces involved in the current requirement, which might include new ones or existing ones. Not all interfaces within a controller may be part of the current requirement.

We are currently looking for a suitable solution, preferably one that can be handled within the configuration file itself.

现在 packageFilter 参数只能过滤到 controller 级别,是否有参数可以支持到单个接口级别?如果目前不支持,是否可以提pr?

由于项目需求在不断推进,接口数量逐渐膨胀。我们会对每个需求新建一个 smart-doc 配置文件,然后在 torna 上创建对应的项目,在此新项目中只包含该需求涉及到的接口,可能有新增,也可能有老接口。一个 controller 内可能不是所有接口都参与到当前需求之中。

目前在找一个合适的解决方案,最好是在配置文件内就可以搞定

@shalousun
Copy link
Collaborator

shalousun commented Jun 16, 2023

@Fioooooooo You can submit a PR to enhance packageFilter to support method-level filtering, as packageFilter itself supports regular expression configuration. If it's a microservice, it's still recommended to push by module. Changing the smart-doc configuration file has a downside in that everyone might modify the file, making it difficult to manage team collaboration uniformly. There isn't really a perfect solution for pushing updates. The ideal approach would be to configure it once and not need to make individual modifications later on.
可以提pr把packageFilter支持到方法级别,packageFilter本身是支持到正则配置的。如果是微服务,还是建议按模块去推送。改smart-doc的配置文件其实有个弊端是每个人可能都会修改文件,团队协作上难统一管理。推送其实还是没有特别好的方案。优雅的应该就是一次配置后不需要单独修改。

@Fioooooooo
Copy link
Contributor Author

Fioooooooo commented Jun 16, 2023

@shalousun Given our current situation with fewer people and more requirements, it's not feasible to have each person dedicated to maintaining a service. With various demands requiring constant patching, pushing documentation based on requirement dimensions is clear at a glance, eliminating the need to search through a multitude of interfaces for those involved this time.

Regarding the mentioned drawbacks, we are now prioritizing documentation. From the outset of a requirement, everyone starts by building the interface documentation using smart-doc. Subsequent development is based on the documentation, and there's rarely a need to modify the configuration file anymore.
我们现在人少需求多,没办法做到每个人专门维护一个服务。各种需求修修补补,以需求为维度推送文档可以一目了然,不用在一堆接口里去找这次涉及到哪些。

关于提到的弊端,我们现在是文档先行。需求一开始,大家先基于 smart-doc 构建出接口文档。后续基于文档开发,很少再去修改配置文件。

@shalousun
Copy link
Collaborator

shalousun commented Jun 18, 2023

@Fioooooooo Feel free to check out #520 if you're interested.

Fioooooooo added a commit to Fioooooooo/smart-doc that referenced this issue Jun 18, 2023
@shalousun shalousun added this to the 2.7.1 milestone Jun 19, 2023
@Fioooooooo
Copy link
Contributor Author

Fioooooooo commented Jun 20, 2023

@shalousun When is version 2.7.1 scheduled to be released?

@shalousun
Copy link
Collaborator

shalousun commented Jun 20, 2023

@shalousun 2.7.1 When is version 2.7.1 scheduled to be released?
节后吧

@shalousun shalousun changed the title 文档只输出指定接口 The documentation only outputs the specified interface. May 22, 2024
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

No branches or pull requests

2 participants