docs: expand API-first workflow guidance

[Olusammytee]

Summary

• Add an end-to-end API-first workflow that pairs OpenAPI with JDL
• Show how to align OpenAPI DTO packages with JHipster defaults
• Include MapStruct mapping example and guidance on delegate-only endpoints

Related

• Fixes Improve Doing API First Development documentation generator-jhipster#27215

[netlify]

✅ Deploy Preview for jhipster-site ready!

Name	Link
🔨 Latest commit	f863e40
🔍 Latest deploy log	https://app.netlify.com/projects/jhipster-site/deploys/698283fcc3632800081783f9
😎 Deploy Preview	https://deploy-preview-1559--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 project configuration.

[Copilot]

Pull request overview

Expands the “Doing API-First development” documentation with an end-to-end contract-first workflow that combines OpenAPI-generated endpoints with JDL-generated domain/service scaffolding.

Changes:

• Updates the doc last_update timestamp.
• Adds a hybrid OpenAPI + JDL workflow with a sample JDL, package-alignment guidance, and MapStruct mapping example.
• Adds guidance on keeping only OpenAPI delegate/controller endpoints by removing JHipster-generated REST controllers.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

The JDL snippet enables dto * with mapstruct, which will generate JHipster DTO classes (typically in ...service.dto) and mappers. This conflicts with the later steps that describe using OpenAPI-generated DTOs/models (and may also collide with the manual PetMapper example below). Consider either removing the dto * with mapstruct line from the example (and keeping only entities/services), or explicitly documenting that teams must choose between JHipster-generated DTOs vs OpenAPI-generated models and keep them in separate packages to avoid class/name collisions.

[Copilot]

This step says "keep OpenAPI-generated DTOs in the same package JHipster uses by default", but earlier on this page the documented default OpenAPI generator modelPackage is ...service.api.dto (see the Maven config above). The wording here is ambiguous and can lead readers to change packages in a way that conflicts with JHipster’s OpenAPI defaults and/or JDL-generated DTOs. Suggest clarifying that ...service.dto is the default package for JHipster entity DTOs, while OpenAPI models default to ...service.api.dto to avoid clashes.

[Copilot]

The MapStruct example uses PetDTO, but the rest of this guide’s OpenAPI generator example produces model classes like Pet (not PetDTO) under the configured modelPackage (later tree shows Pet.java, and the delegate examples import ...service.api.dto.Pet). To avoid confusing readers, align this example with the actual generated model names/packages (or explicitly mention/configure modelNameSuffix/renaming if you intend *DTO types).

Suggested change

	### 3) Map OpenAPI DTOs to entities with MapStruct
	JHipster's recommended approach for DTO mapping is MapStruct. You can map the OpenAPI-generated DTOs to your JPA entities in a standard `service.mapper` package. See [Using DTOs](/using-dtos/) for more examples.
	```java
	package demo.jhipster.myapp.service.mapper;
	import demo.jhipster.myapp.domain.Pet;
	import demo.jhipster.myapp.service.dto.PetDTO;
	import org.mapstruct.Mapper;
	@Mapper(componentModel = "spring")
	public interface PetMapper {
	Pet toEntity(PetDTO dto);
	PetDTO toDto(Pet entity);
	### 3) Map OpenAPI models to entities with MapStruct
	JHipster's recommended approach for DTO mapping is MapStruct. You can map the OpenAPI-generated API models to your JPA entities in a standard `service.mapper` package. See [Using DTOs](/using-dtos/) for more examples.
	```java
	package demo.jhipster.myapp.service.mapper;
	import demo.jhipster.myapp.domain.PetEntity;
	import demo.jhipster.myapp.service.api.dto.Pet;
	import org.mapstruct.Mapper;
	@Mapper(componentModel = "spring")
	public interface PetMapper {
	PetEntity toEntity(Pet apiModel);
	Pet toApiModel(PetEntity entity);

[Copilot]

The heading says "Disable default REST controllers", but the text describes manually removing web/rest controllers after generation. Since there’s no documented switch here to actually disable generation, consider renaming this step to reflect the real action (e.g., removing/keeping them out of the final codebase) to avoid implying there’s a supported toggle.

Suggested change

	### 4) Disable default REST controllers (delegate-only endpoints)
	When you generate entities from JDL, JHipster will also generate REST controllers under `src/main/java/.../web/rest`. In a strict API-First approach, those controllers are typically removed so that only the OpenAPI-generated `*ApiController` and `*ApiDelegate` classes expose endpoints. If you regenerate entities later, you may need to remove the `web/rest` controllers and their tests again or keep them in a separate commit to avoid accidental exposure of endpoints outside the contract.
	### 4) Remove generated REST controllers (delegate-only endpoints)
	When you generate entities from JDL, JHipster will also generate REST controllers under `src/main/java/.../web/rest`. In a strict API-First approach, those controllers are typically removed manually (there is no generator option to skip them) so that only the OpenAPI-generated `*ApiController` and `*ApiDelegate` classes expose endpoints. If you regenerate entities later, you may need to remove the `web/rest` controllers and their tests again or keep them in a separate commit to avoid accidental exposure of endpoints outside the contract.