Avant de générer le fichier OpenAPI complet, il faut préciser une contrainte importante :
Le contrat OpenAPI complet correspondant à ce projet représente environ :
Il est impossible de produire l'intégralité du fichier dans une seule page wiki ou dans une seule réponse.
La bonne pratique consiste à structurer la spécification comme un projet OpenAPI modulaire.
docs/openapi/ openapi.yaml components/ ├── schemas │ ├── parameters │ ├── responses │ ├── requestBodies │ └── securitySchemes paths/ ├── auth.yaml ├── users.yaml ├── owners.yaml ├── properties.yaml ├── reservations.yaml ├── contracts.yaml ├── payments.yaml ├── crm.yaml ├── messaging.yaml ├── reporting.yaml └── administration.yaml
openapi: 3.1.0 info: title: Rental Platform API version: 1.0.0 description: > Property Rental Management Platform servers: - url: https://api.production.com/api/v1 - url: https://api.staging.com/api/v1 security: - bearerAuth: [] tags: - name: Auth - name: Users - name: Owners - name: Properties - name: Reservations - name: Contracts - name: Payments - name: CRM - name: Messaging - name: Reporting paths: /auth/login: $ref: './paths/auth.yaml#/login' /properties: $ref: './paths/properties.yaml#/properties' components: securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: JWT
login: post: tags: - Auth summary: Login operationId: login requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/LoginRequest' responses: '200': description: Login success content: application/json: schema: $ref: '#/components/schemas/LoginResponse' '401': description: Invalid credentials
LoginRequest: type: object required: - email - password properties: email: type: string format: email password: type: string minLength: 8
LoginResponse: type: object properties: accessToken: type: string refreshToken: type: string expiresIn: type: integer
Property: type: object required: - id - title - status properties: id: type: string format: uuid code: type: string title: type: string minLength: 5 maxLength: 255 status: $ref: '#/components/schemas/PropertyStatus' surface: type: number roomCount: type: integer bedroomCount: type: integer bathroomCount: type: integer capacity: type: integer createdAt: type: string format: date-time
PropertyStatus: type: string enum: - DRAFT - PUBLISHED - RENTED - MAINTENANCE - ARCHIVED
properties: get: tags: - Properties summary: Search properties operationId: searchProperties parameters: - $ref: '#/components/parameters/Page' - $ref: '#/components/parameters/PageSize' - name: city in: query schema: type: string - name: minPrice in: query schema: type: number - name: maxPrice in: query schema: type: number responses: '200': description: Property list content: application/json: schema: $ref: '#/components/schemas/PaginatedProperties'
post: tags: - Properties summary: Create property operationId: createProperty requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreatePropertyRequest' responses: '201': description: Property created content: application/json: schema: $ref: '#/components/schemas/Property'
Reservation: type: object properties: id: type: string format: uuid reservationNumber: type: string startDate: type: string format: date endDate: type: string format: date totalAmount: type: number status: $ref: '#/components/schemas/ReservationStatus'
ReservationStatus: type: string enum: - PENDING - CONFIRMED - SIGNED - COMPLETED - CANCELLED
post: tags: - Reservations summary: Create reservation operationId: createReservation requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateReservationRequest' responses: '201': description: Reservation created content: application/json: schema: $ref: '#/components/schemas/Reservation'
Payment: type: object properties: id: type: string format: uuid amount: type: number status: $ref: '#/components/schemas/PaymentStatus' paymentDate: type: string format: date-time
PaymentStatus: type: string enum: - PENDING - AUTHORIZED - PAID - FAILED - REFUNDED
Page: name: page in: query schema: type: integer minimum: 1
PageSize: name: pageSize in: query schema: type: integer minimum: 1 maximum: 100
PaginationMeta: type: object properties: page: type: integer pageSize: type: integer total: type: integer pages: type: integer
ErrorResponse: type: object properties: success: type: boolean example: false error: type: object properties: code: type: string message: type: string
VALIDATION_ERROR UNAUTHORIZED FORBIDDEN NOT_FOUND CONFLICT INTERNAL_ERROR
type: string format: uuid
type: string format: email
type: string format: date
type: string format: date-time
À partir de cette spécification, génération :
DTO NestJS Swagger Validation Tests contractuels
SDK TypeScript Hooks TanStack Query Schemas Zod Types TypeScript
SDK Flutter SDK React Native
Le projet complet nécessitera :
| Élément | Volume |
|---|---|
| Modules API | 11 |
| Endpoints | ~250 |
| DTO | ~200 |
| Schémas | ~150 |
| Lignes YAML | 8 000 à 15 000 |
La prochaine étape réellement productive n'est plus documentaire mais générative.
À partir de tout ce qui a été produit, il devient pertinent de générer automatiquement :
afin d'obtenir le premier socle de code exécutable du projet.
C'est généralement à ce stade que démarre effectivement le développement logiciel.