Real World Example

Swiggy, Zomato and Flipkart show the same item in many places: a small card in search results, a full detail page, and an admin view for sellers with cost and margin. One entity, several DTOs:

public record ProductCard(Long id, String name, BigDecimal price, boolean inStock) {}

public record ProductDetail(Long id, String name, String description,
                            BigDecimal price, int stock, String category) {}

@RestController
@RequestMapping("/api/products")
public class ProductController {
    private final ProductService service;
    private final ProductMapper mapper;

    public ProductController(ProductService service, ProductMapper mapper) {
        this.service = service;
        this.mapper = mapper;
    }

    @GetMapping
    public List<ProductCard> list() {
        return service.findAll().stream().map(mapper::toCard).toList();
    }

    @GetMapping("/{id}")
    public ProductDetail get(@PathVariable Long id) {
        return mapper.toDetail(service.getById(id));
    }

    @PostMapping
    @ResponseStatus(HttpStatus.CREATED)
    public ProductDetail create(@RequestBody CreateProductRequest request) {
        return mapper.toDetail(service.create(mapper.toEntity(request)));
    }
}

curl localhost:8080/api/products
curl localhost:8080/api/products/1

[{"id":1,"name":"Wireless Mouse","price":799.00,"inStock":true},{"id":2,"name":"Clean Code","price":450.00,"inStock":false}]
{"id":1,"name":"Wireless Mouse","description":"2.4 GHz, silent clicks","price":799.00,"stock":120,"category":"Electronics"}

curl -X POST localhost:8080/api/products -H "Content-Type: application/json" -d '{"id":999,"costPrice":1,"name":"USB-C Cable","description":"1 m braided","price":299.00,"stock":500,"category":"Electronics"}'

{"id":3,"name":"USB-C Cable","description":"1 m braided","price":299.00,"stock":500,"category":"Electronics"}