docs: rewrite API first guide with detailed implementation and samples #1335
Conversation
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.
✅ Deploy Preview for jhipster-site ready!
To edit notification comments on pull requests, go to your Netlify site configuration. |
Both plugins have been retired by Apache Maven. See: https://maven.apache.org/plugins/#retired for more details. Both plugins have not see updates in almost a decade (IDEA was last updated in 2013). The mention and use of the plugins has been removed from the Doing API First Development guide in jhipster/jhipster.github.io#1335. Closes jhipster#25081
JHipster defaults the `/api/**` behind authentication via the SecurityConfigurationFilter chain, e.g., `.authenticated()`. It is possible to craft a JWT Bearer token to test the API using the JWT Secret generated by JHipster during creation.
|
@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, jhipster/generator-jhipster#25030 (comment). 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.
|
|
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. |
Test the desired URL to help Jekyll with redirects
|
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. |
|
@mraible @atomfrede who watches and reviews these JHipster.tech PRs? Anyone I should tag? |
|
Hi @timothystone-knsl I'm currently on vacation and don't have time to review. It's possible I will in the coming weeks. |
|
Sorry @timothystone-knsl I wanted to have a look. Will try it this week. |
|
I too just returned from vacation. Just poking this PR. |
Update docs to reflect OpenAPI implementation recommendation.
|
@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 In the guide (blob link), it is explicitly called out:
This may be true, but the generated code does not resolve this "provided How can I help close this gap and provide the necessary tips or instructions for new users of JHipster in "providing the bean" properly? |
| ❯◉ API first development using OpenAPI-generator | ||
| ``` | ||
|
|
||
| This option will configure the build tool, Maven or Gradle, to use the openapi-generator-maven-plugin to generate API code from an OpenAPI (Swagger) Specification (OAS) file. Both Swagger v2 and OpenAPI v3 formats are supported. |
There was a problem hiding this comment.
Maybe just to avoid confusion, don't mention the build tool and just use openapi-generator-plugin?
| - You can design your API for the consumers and not as a consequence of your implementation. | ||
| - You can use the specification file to mock your new server endpoints before they are released so you can more decouple frontend and backend development. | ||
| - You don't need a live server to use your OpenAPI documentation. | ||
| Hereafter, this guide will be based on a [JHipster-ready version of Expanded Pet Store v3](api/api.yml) from the OpenAPI Initiative ([found here](https://github.com/OAI/OpenAPI-Specification/blob/main/examples/v3.0/petstore-expanded.yaml)). This JHipster-version sets the `server:url` to the JHipster defaults of `http://localhost:8081/api` (where the port defaults to `8081` and the generated controller has a base path of `/api`, matching the default `SecurityConfiguration#filterChain(HttpSecurity, MvcRequestMatcher.Builder)` implementation). |
There was a problem hiding this comment.
When generating a new microservice, the default is 8081:
? As you are running in a microservice architecture, on which port would like your server to run? It should be unique to
avoid port conflicts. (8081)
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. |
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 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. |
|
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 |
|
@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. |
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