-
-
Notifications
You must be signed in to change notification settings - Fork 4k
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
Improve Doing API First Development documentation #27215
Comments
As soon as I have a PR, I'll reference. |
I'll track my notes in this issue for comment. nb. I will use a mix of shell syntax for brevity; if anything is unclear, please quote reply. My first deep dive into the code and the behaviors show that some of the defaults in JHipster are intentional., for example the This "moves" the generator's DTOs "out of the way" of the default DTOs generated when using So for example...
will generate DTO and Mappers at This is acceptable, but you have to know what is being generated in contrast to the OpenAPI specification to leverage either. Thus no. 2 of the defined goals may be moot. Moreover, JHipster will generate full implementations of Following the guide as written means moving the JHipster controllers out of the way to employ the delegate implementations. NB. The JHipster More to come. |
Totally agrees. Is there a use case where user don't need DTO? Could it be clarified before V9? |
No. The use of the annotation processors in the
Could you elaborate? I think you mean that "ideally JHipster would generate the same operation endpoints for the HTTP mappings, e.g., Right now the |
Overview of the feature request
The current PR for this documentation aims to improve the existing guide from the current starting point.
However, in working with the core JHipster team during #1335 and in my own professional work with JHipster microservices with a Contract First approach ("API First") and the provided tooling of the OpenAPI Maven Generator Plugin, I have found that there are some additional improvements to the guide for an end-to-end API First approach.
This issue (and accompanying PR) intends to track the end-to-end documentation of API-First development with JHipster and fully leveraging both the current JHipster default of the Delegate Pattern and the implementation of the delegates with Mapstruct.
Motivation for or Use Case
IMHO, Contract First/API First development, has a very specific meaning: one starts with the Open API Specification and defers as much work to the tooling as possible, providing implementation details. For example, delegate implementations (using the delegate pattern).
However, as written, the documentation only provides a guide to the implementation of the delegates and provides no guidance on JHipster default behaviors or managing the same. For example:
If you choose "API First ..." in project generation, the project gets a Swagger Docker Compose file, some default settings applied to the project, and an Open API Specification with a single schema for Problem. The documentation currently provides no guidance on the use of DTOs and Entities. More importantly JHipster's default behaviors and configuration work against the API First developer, leaving elements of "cruft." For example: generating entities with JDL, during JHipster initiation (or after) creates implementations that do not take advantage of the initial intent of API First, as default behaviors of JHipster are not "API First Aware."
This improvement will seek to provide documentation on:
Related issues or PR
See PR 1335 (Issue #25030).
This issue and PR will supersede #25030 but should not delay the integration of existing PR, as that PR aims to improve the existing documentation.
The text was updated successfully, but these errors were encountered: