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.

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

[timothystone]

As soon as I have a PR, I'll reference.

[timothystone]

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 <modelPackage> value of the openapi-generator-maven-plugin. It is defined as <package-name>.service.api.dto.

This "moves" the generator's DTOs "out of the way" of the default DTOs generated when using mapstruct in the JDL for the defined entities.

So for example...

application {
  config {
     ...
     enableSwaggerCodegen true
  }
  entities *
  use mapstruct for *
}

entity Foo {
  ...
}

will generate DTO and Mappers at <package.name>.service.{dto,mapper}.

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 @RestControllers for the entities while at the same time the default configuration of the generator employed, c.f. the plugin configuration:generatorName=spring. The spring generator is defaulted to configuration:configOptions:delegatePattern=true. This will generate entity controllers bound to identical HTTP methods based on the paths.

Following the guide as written means moving the JHipster controllers out of the way to employ the delegate implementations.

NB. The JHipster *Resource.java controllers are helpful to the novice user in guiding implementation of the service classes however.

More to come.

[Tcharl]

Totally agrees.
Jhipster should ideally generate an -api.yml per endpoint, and rely on the openapi plugin to generate the controller (delegate mode) and dto.

Is there a use case where user don't need DTO? Could it be clarified before V9?

[timothystone]

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 maven-complier-plugin for mapstruct indeed will generate the Mappers for the DTOs generated by the openapi-generator-maven-plugin.

Jhipster should ideally generate an -api.yml per endpoint, and rely on the openapi plugin to generate the controller (delegate mode) and dto.

Could you elaborate? I think you mean that "ideally JHipster would generate the same operation endpoints for the HTTP mappings, e.g., @GetMapping(String) in the src/main/resources/swagger/api.yml" that it is being generated by the plugin in the delegates. Is that correct?

Right now the api.yml only includes the Problem schema.