openapi-tools
Add support for static HTML page generation with input from Handlebars template
Is your feature request related to a problem? Please describe. I am able to generate the Swagger specification file in JSON and YAML, but I need to generate a static HTML document from the specification that can be hosted separately.
Describe the solution you'd like It would be comfortable to have a configuration that would let us enable the generation of a static HTML while using a handlebars template. Also, a nested config that will have a default name for the generated html file, but can also be customized as per requirement.
Describe alternatives you've considered I'm not aware of alternative that I can use. Any suggestion is welcome that can solve the problem.
Additional context The feature is provided by Swagger plugin from Yukai Kong but it doesn't seem to be working with Swagger v3 annotations. It takes a Handlebars template to generate the static html document.
My initial thought would be to do this as a separate step instead of including it in this plugin. The initial idea was to create a wrapper as thin as possible around the functionality provided by the Swagger project itself. I would use the yaml or json together with a templating framework of choice to render a html version (possibly including the Swagger UI library)
That's true.
Just for reference, the task can be achieved with the swagger-codegen-maven-plugin.
But the problem is, this the openapitools/swagger-maven-plugin works in the prepare-package phase while the codegen plugin works in the compile phase. It would be helpful if the openapitools/swagger-maven-plugin can also be used it the compile phase as sometimes it's not possible/feasible to build a project just for the documentation.
Yeah, now it has been some years since I did the first parts of this. As far as I recall the reason for doing it in prepare-package is because Swagger works on the compiled classes, not the source code. Hence, we need to be sure the project is built before running Swagger. You might be able to attach to the process-classes lifecycle instead, that would allow for skipping at least test - I think you would be able to test this by means of the plugin configuration in the pom.xml overriding the default lifecycle binding.
@langecode That sounds good, and it does make sense to work on the compiled classes.
That apart, would it be possible to run the swagger-codegen-plugin as part of this plugin? At least that can help to generate static documentation, even if not template-based.