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

Inject Markdown files from filesystem into operation description #28

Closed
nandorholozsnyak opened this issue Jan 17, 2023 · 0 comments · Fixed by #29
Closed

Inject Markdown files from filesystem into operation description #28

nandorholozsnyak opened this issue Jan 17, 2023 · 0 comments · Fixed by #29
Assignees
Labels
enhancement New feature or request new-feature Non existing feature request or proposal

Comments

@nandorholozsnyak
Copy link
Member

nandorholozsnyak commented Jan 17, 2023

Is your feature request related to a problem? Please describe.
Developers tend to write descriptions for their endpoints but sometimes they can be super long and to write this into the production code can be fine until it is not.

Most times we recommend to break the rest controller into interface and implementations pairs, the interface can have the OpenAPI documentation descriptors and the Spring based annotations, and the implementation can be pure Java code.

As most editors are having Markdown support it can be wise to inject the descriptions from Markdown files and do not write lengthy descriptions in the annontations. With Java's text blocks it can be handy but still not good to write, because of the style and indentations.

Describe the solution you'd like
Markdown files could be put into the resources folder and upon startup the app would read them and would inject it into the specific operation's description:

File name suggestion priority:

  • Custom extension
  • operationId.md - in case of ambiguous warning log and no injection
  • ControllerClassName.method.md

Custom extension:

    @Operation(extensions = {
        @Extension(name = "x-extender-description", properties = {@ExtensionProperty(name = "source", value = "CustomFile.md"))
    }))
@nandorholozsnyak nandorholozsnyak added enhancement New feature or request new-feature Non existing feature request or proposal labels Jan 17, 2023
@nandorholozsnyak nandorholozsnyak self-assigned this Jan 17, 2023
nandorholozsnyak added a commit that referenced this issue Jan 18, 2023
…description

- Injecting operation's description from resource with different resource loading mechanisms
nandorholozsnyak added a commit that referenced this issue Jan 20, 2023
…description

- Tests for the loaders and service
- Async summary injection
nandorholozsnyak added a commit that referenced this issue Jan 22, 2023
…description

- Documentation about the resource injection feature
nandorholozsnyak added a commit that referenced this issue Jan 22, 2023
…description

- Documentation about the resource injection feature #2
nandorholozsnyak added a commit that referenced this issue Jan 22, 2023
…description

- Image about the setup for extra summaries
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
enhancement New feature or request new-feature Non existing feature request or proposal
Projects
None yet
Development

Successfully merging a pull request may close this issue.

1 participant