docs: rewrite API first guide with detailed implementation and samples

[timothystone-knsl]

Re-ordered concepts to introduce concepts provided by JHipster with details on the out of the box configuration of the openapi-generator and the use of the Delegate Pattern. Explicitly callout the use of the OAI's Pet Store example with links to samples.

Added notes on JHipster's technical structure and the use of ArchUnit to prepare the reader for the implementation of the API operations.

Rewrite and editdocs for a detailed introduction of API first development

NOTE: removed references to the Maven IDEA and Eclipse plugins. Both have been retired and should be removed from JHipster.

Added detailed examples of the implementation of NativeWebRequest and responses

Lots of examples and details added to both the basic and detailed implementation with mock request responses prior to implementation with the NativeWebRequest.

Add sample api.yml used in guide and build out initial content

The content is largely complete and ready for review. Add links and the sample api.yml document used throughout the guide.

Closes jhipster/generator-jhipster#25030

[netlify[bot]]

✅ Deploy Preview for jhipster-site ready!

Name	Link
🔨 Latest commit	6a5a99468e4204147971e66aef3da7fd8adaae38
🔍 Latest deploy log	https://app.netlify.com/sites/jhipster-site/deploys/66733299980eff0008c3c041
😎 Deploy Preview	https://deploy-preview-1335--jhipster-site.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify site configuration.

[timothystone-knsl]

@mraible see above deployment and attempt navigation to the proposed changes in Options > Doing API First Development. The redirect is broken an in an infinite loop. See also the issue and this comment for more context, https://github.com/jhipster/generator-jhipster/issues/25030#issuecomment-1925869198.

I'm alerting you because I just found this in the Netlify deployment checks... you or somebody on the team may wish to look into the redirect looping.

[mraible]

Does it work when you run it locally? I've seen this happen with other pages, but I'm not sure how to fix it.

[timothystone-knsl]

Does it work when you run it locally? I've seen this happen with other pages, but I'm not sure how to fix it.

I haven't went that far yet... but I'll try today, time permitting. Thanks for looking! Sorry to pick on you... but I saw your name "Matt Raible's Team" and decided it was worth a tag.

[timothystone-knsl]

Moving the conversation from the jhipster/generator-jhipster#25030.

Basically a full rewrite of the API First document with sample files, consistent examples, and explanations for new comers. Includes configuration of the plugins and sample code showing full context. Removed references to retired tooling, see jhipster/generator-jhipster#25081 (merged). Added authentication tips (and a couple of Pro Tips).

Since the Netlify deployment doesn't work, the edits can be reviewed in context here.

[timothystone-knsl]

@mraible @atomfrede who watches and reviews these JHipster.tech PRs? Anyone I should tag?

[mraible]

Hi @timothystone-knsl I'm currently on vacation and don't have time to review. It's possible I will in the coming weeks.

[atomfrede]

Sorry @timothystone-knsl I wanted to have a look. Will try it this week.

[timothystone-knsl]

I too just returned from vacation. Just poking this PR.

[timothystone-knsl]

@mraible @atomfrede I'm still interested in making this guide more approachable and removing what I see as assumption gaps in the existing guide.

One thing I need to resolve and it's not obvious to me is that the OpenAPI Generator as configured to useDelegates=true requires an implementation.

In the guide (blob link), it is explicitly called out:

Providing the NativeWebRequest bean to the Delegate interface can return example response bodies for the methods that have not been overridden. The endpoints still respond with a 501 Not Implemented HTTP status code, but the example response may be useful for mocking endpoints before the actual implementation.

This may be true, but the generated code does not resolve this "provided NativeWebRequest bean" in the IDE. One of the things I'm trying to do with the rewrite is to close some assumption gaps, where the assumptions are made by experienced users of the frameworks and tooling as configured by default in JHipster, i.e., delegatePattern=true (where this default is even debated in some forums as necessary or "unnecessary complexity").

How can I help close this gap and provide the necessary tips or instructions for new users of JHipster in "providing the bean" properly?

[atomfrede]

@mraible @atomfrede I'm still interested in making this guide more approachable and removing what I see as assumption gaps in the existing guide.

One thing I need to resolve and it's not obvious to me is that the OpenAPI Generator as configured to useDelegates=true requires an implementation.

In the guide (blob link), it is explictly called out:

Providing the NativeWebRequest bean to the Delegate interface can return example response bodies for the methods that have not been overridden. The endpoints still respond with a 501 Not Implemented HTTP status code, but the example response may be useful for mocking endpoints before the actual implementation.

This may be true, but the generated code does not resolve this "provided NativeWebRequest bean" in the IDE. One of the things I'm trying to do with the rewrite is to close some assumption gaps, where the assumptions are made by experienced users of the frameworks and tooling as configured by default in JHipster, i.e., useDelegate=true (where this default is even debated in some forums as necessary or "unnecessary complexity").

How can I help close this gap and provide the necessary tips or instructions for new users of JHipster in "providing the bean" properly?

What is the issue with the nativeWebRequets and the IDE? When it comes to delegate use, this could be changed if we agree its not needed. At least in my projects (not jhipster ones) we have always used delegates as far as I remember.

[timothystone-knsl]

What is the issue with the nativeWebRequests and the IDE? When it comes to delegate use, this could be changed if we agree its not needed. At least in my projects (not jhipster ones) we have always used delegates as far as I remember.

I don't have a real issue with the use of the delegate pattern. Where the discussion occurs it is around preferences and is mostly a question for me of: is JHipster providing the pattern as an example of best practice or if interfaceOnly would be "more approachable." The delegatePattern=true is not the default, but delegatePattern=false so JHipster is making a deliberate decision here.

In IntelliJ, one will often see this:

It doesn't seem to impact anything... at least casually, but I've been asked about it and don't have an answer. My Spring experience has its own gaps and I have not been able to resolve this myself. It feels as if the OpenAPI generator is not doing something and there is a gap in the documentation that can address it.

[atomfrede]

Good point. I really can not recall any explicit decision for delagate pattern. If we do not have one we should adhere to our policy to use technologies with their default config (when possible)

[timothystone-knsl]

Good point. I really can not recall any explicit decision for delagate pattern. If we do not have one we should adhere to our policy to use technologies with their default config (when possible)

On that, the following would need to be changed or removed in the generator. See also the documentation for the Spring Generator defaults.

If there as simple Spring configuration fix that would address the "missing bean" in the IDE, whether a PR in the OpenAPI plugin or in the src/main/java/**/config package I'm happy to take that on as part of both the documentation PR and in the generator.

[mraible]

@timothystone-knsl I don't know much about this as I haven't used this feature. A PR would be most welcome if it makes things better.

[timothystone-knsl]

Updated, removing the old note on using jhipster openapi-client subgenerator as that is no longer maintained since v8.

I might ask a separate question: why have the option in jhipster --help? Maybe allow the use for those looking to use it and report the error as today, but not list it in the usage output?