JHipster’s Built‑in OpenAPI Support: Automate API Docs and Keep Them In Sync

Why Automatic API Docs Matter in JHipster

When a JHipster project is scaffolded with the swagger or openapi option, the generator wires up Springdoc OpenAPI. The result is a live /v3/api-docs JSON endpoint and a Swagger UI that reflects every @RestController and repository paging parameter without any manual edits.

What JHipster Adds Under the Hood

• Dependency: org.springdoc:springdoc-openapi-starter-webmvc-ui (Springdoc 2.x in JHipster 7.10+).
• Configuration bean that exposes /v3/api-docs and serves Swagger UI at /swagger-ui/index.html.
  • Earlier JHipster versions use /swagger-ui.html.
• Automatic inclusion of all controller methods, request/response classes, and Spring Data paging parameters.
• YAML overrides: jhipster.yml or application.yml can set openapi.title, openapi.description, openapi.version, and security schemes.

Concrete Step‑by‑Step Example

1. Generate a project

   jhipster --blueprints swagger --force
   # or add the option during interactive setup
   

   When prompted for an option, choose swagger (or openapi) to add the dependency automatically.

2. Run the app

   ./mvnw spring-boot:run
   

   Requires Maven 3.6+ and Java 17+ (the default JHipster stack).

3. Verify the JSON schema

   curl http://localhost:8080/v3/api-docs | head -n 20
   

   You should see a JSON document starting with {"openapi":"3.1.0", "info":{...}}. If the endpoint returns 404, check that Spring Security isn’t blocking it.

4. Open the Swagger UI

   open http://localhost:8080/swagger-ui/index.html
   

   All generated entities (e.g., User, Post) appear as operations. Adding a new field to an entity and regenerating it with jhipster entity automatically updates the UI on the next refresh.

5. Override metadata

   # In src/main/resources/config/application.yml
   jhipster:
     swagger:
       title: "My App API"
       description: "Public API for the My App service"
       version: "2.0"
   

   Restart the app to see the changes reflected in the JSON and UI.

Trade‑Offs and Practical Limitations

• Endpoint exposure in production: /v3/api-docs is public by default. If your service contains internal endpoints, secure it with Spring Security:

  spring:
    security:
      oauth2:
        resourceserver:
          jwt:
            issuer-uri: https://auth.example.com
  

  or add a custom SecurityFilterChain that permits only authenticated users.

• Path differences: 2.x Springdoc uses /swagger-ui/index.html; 1.x used /swagger-ui.html. Adjust your documentation links accordingly if you upgrade.
• Large schemas: Complex projects can generate huge JSON files that slow the UI. Consider enabling springdoc.api-docs.groups to split the spec.

Actionable Checklist for Your Project

• Include the OpenAPI option when creating or updating a JHipster app.
• Verify /v3/api-docs is reachable during development.
• Secure the endpoint in application-prod.yml if the app is exposed to the internet.
• Use jhipster entity to regenerate entities; the docs update automatically.
• Document custom security schemes in jhipster.yml to keep the spec accurate.

Conclusion

JHipster’s OpenAPI integration turns API documentation from a static artifact into a live reflection of your code. With minimal configuration, you get a browsable UI, a consumable JSON spec, and automatic updates whenever you change an entity. The main caveat is ensuring the docs endpoint is appropriately secured for production deployments.