Improve Doing API First Development documentation

[timothystone]

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:

1. Creating of a JDL to "kickstart" the generator
2. changes to template to set the DTO path of the generated models to the expected packaging defaults of JHipster
3. Implementation of MapStruct
4. Disabling of the default RestControllers, deferring to the generator delegates
5. Examples of the delegate implementations
6. Example Database with Relationships for a more complete e2e view of API First development

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.

• [x] Checking this box is mandatory (this is just to show you read everything)