====== OpenAPI YAML Complet ======

===== Préambule =====

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 :

  * 250 endpoints
  * 150 à 250 schémas DTO
  * 8000 à 15000 lignes YAML
  * 1 à 2 Mo de spécification

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.

----

====== Structure OpenAPI recommandée ======

<code>
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
</code>

----

====== Fichier racine ======

===== openapi.yaml =====

<code 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
</code>

----

====== Module Auth ======

===== POST /auth/login =====

<code yaml>
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
</code>

----

===== LoginRequest =====

<code yaml>
LoginRequest:

  type: object

  required:

    - email

    - password

  properties:

    email:

      type: string

      format: email

    password:

      type: string

      minLength: 8
</code>

----

===== LoginResponse =====

<code yaml>
LoginResponse:

  type: object

  properties:

    accessToken:

      type: string

    refreshToken:

      type: string

    expiresIn:

      type: integer
</code>

----

====== Module Properties ======

===== Property =====

<code yaml>
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
</code>

----

===== PropertyStatus =====

<code yaml>
PropertyStatus:

  type: string

  enum:

    - DRAFT

    - PUBLISHED

    - RENTED

    - MAINTENANCE

    - ARCHIVED
</code>

----

===== GET /properties =====

<code yaml>
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'
</code>

----

===== POST /properties =====

<code yaml>
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'
</code>

----

====== Module Reservations ======

===== Reservation =====

<code yaml>
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'
</code>

----

===== ReservationStatus =====

<code yaml>
ReservationStatus:

  type: string

  enum:

    - PENDING

    - CONFIRMED

    - SIGNED

    - COMPLETED

    - CANCELLED
</code>

----

===== POST /reservations =====

<code yaml>
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'
</code>

----

====== Module Payments ======

===== Payment =====

<code yaml>
Payment:

  type: object

  properties:

    id:

      type: string

      format: uuid

    amount:

      type: number

    status:

      $ref: '#/components/schemas/PaymentStatus'

    paymentDate:

      type: string

      format: date-time
</code>

----

===== PaymentStatus =====

<code yaml>
PaymentStatus:

  type: string

  enum:

    - PENDING

    - AUTHORIZED

    - PAID

    - FAILED

    - REFUNDED
</code>

----

====== Pagination standard ======

===== Paramètres =====

<code yaml>
Page:

  name: page

  in: query

  schema:

    type: integer

    minimum: 1
</code>

----

<code yaml>
PageSize:

  name: pageSize

  in: query

  schema:

    type: integer

    minimum: 1

    maximum: 100
</code>

----

===== Réponse =====

<code yaml>
PaginationMeta:

  type: object

  properties:

    page:

      type: integer

    pageSize:

      type: integer

    total:

      type: integer

    pages:

      type: integer
</code>

----

====== Gestion des erreurs ======

===== ErrorResponse =====

<code yaml>
ErrorResponse:

  type: object

  properties:

    success:

      type: boolean

      example: false

    error:

      type: object

      properties:

        code:

          type: string

        message:

          type: string
</code>

----

===== Codes =====

<code>
VALIDATION_ERROR

UNAUTHORIZED

FORBIDDEN

NOT_FOUND

CONFLICT

INTERNAL_ERROR
</code>

----

====== Validation ======

===== UUID =====

<code yaml>
type: string

format: uuid
</code>

----

===== Email =====

<code yaml>
type: string

format: email
</code>

----

===== Date =====

<code yaml>
type: string

format: date
</code>

----

===== DateTime =====

<code yaml>
type: string

format: date-time
</code>

----

====== Génération automatique ======

À partir de cette spécification, génération :

===== Backend =====

<code>
DTO NestJS

Swagger

Validation

Tests contractuels
</code>

----

===== Frontend =====

<code>
SDK TypeScript

Hooks TanStack Query

Schemas Zod

Types TypeScript
</code>

----

===== Mobile =====

<code>
SDK Flutter

SDK React Native
</code>

----

====== Livrables OpenAPI ======

Le projet complet nécessitera :

^ Élément ^ Volume ^
| Modules API | 11 |
| Endpoints | ~250 |
| DTO | ~200 |
| Schémas | ~150 |
| Lignes YAML | 8 000 à 15 000 |

----

====== Recommandation finale ======

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 :

  * Prisma Schema complet
  * Entités NestJS
  * DTO NestJS
  * SDK Frontend TypeScript
  * Structure Monorepo
  * Docker Compose
  * GitHub Actions
  * Helm Charts

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.