Automatically generating the OpenAPI specification file can be a good practice in some cases, but there are several reasons why you might want to avoid it:
Accuracy: Automatically generated specifications can sometimes miss out on details or not fully capture the nuances of your API. This can lead to inaccuracies in the generated documentation or client SDKs.
Customization: When you generate the specification automatically, you might not have as much control over the final output. This can limit your ability to customize the documentation or the structure of the specification.
Maintenance: If your API changes frequently, maintaining an automatically generated specification can become challenging. You would need to regenerate the specification every time there's a change in the API.
Performance: The process of generating the specification can add overhead to your build or deployment process, which might not be desirable in some cases.
Security: If the generation process is not properly secured, it could potentially expose sensitive information about your API.
Wanted
We want to maintain our openapi spec files manually so that we have full control over the specification. Furthermore we don't want to rely on any 3rd party generators & gradle build steps.
Solution
(Re)Write the openapi spec files manually (check what can be re-used).
Generate the new client code in a new gradle module sechub-openapi-java
Remove any reduced-openapi.yaml files
Refactor the gradle build steps so that we don't have any dependencies between build steps which were necessary to generate the openapi spec.
Any non-included gradle modules (like web-ui) should now be included into the overall gradle build normally.
Situation
Automatically generating the OpenAPI specification file can be a good practice in some cases, but there are several reasons why you might want to avoid it:
Accuracy: Automatically generated specifications can sometimes miss out on details or not fully capture the nuances of your API. This can lead to inaccuracies in the generated documentation or client SDKs.
Customization: When you generate the specification automatically, you might not have as much control over the final output. This can limit your ability to customize the documentation or the structure of the specification.
Maintenance: If your API changes frequently, maintaining an automatically generated specification can become challenging. You would need to regenerate the specification every time there's a change in the API.
Performance: The process of generating the specification can add overhead to your build or deployment process, which might not be desirable in some cases.
Security: If the generation process is not properly secured, it could potentially expose sensitive information about your API.
Wanted
We want to maintain our openapi spec files manually so that we have full control over the specification. Furthermore we don't want to rely on any 3rd party generators & gradle build steps.
Solution
sechub-openapi-javareduced-openapi.yamlfiles