Specifica OpenAPI

Outcome: Complete the task with Specifica OpenAPI (OpenAPI Specification). User context: Un'API partner descrive `POST /claims` e l'intestazione di idempotenza richiesta. Elenca anche lo scope OAuth, le regole dello schema JSON, le risposte 201 e di problema, ed esempi con dati fittizi. Il CI blocca una risposta che rompeva il sistema e non era documentata. I client generati vengono comunque revisionati invece di essere considerati affidabili senza controlli. Technical concept or control: Specifica OpenAPI (OpenAPI Specification). Why it fits: Usalo come contratto che le persone possono esaminare per documentazione, controlli, server mock, generazione client e test di compatibilità. Do not use it when: I documenti generati non sostituiscono esempi reali, test di autorizzazione, controlli a runtime o comportamento chiaro in produzione. Engineering requirements: Define inputs, outputs, contracts, and rules that must always hold. Set authorization and input checks. Define failures, timeouts, retries, one-time effects, data moves, and compatibility limits. Operations: Add useful signals and logs that hide sensitive data. Set capacity limits and write an operator guide. Test recovery and rollback. Acceptance criteria: Contract and failure-path tests pass. Data and authorization rules still hold during retries and partial failures. Check performance limits, monitoring, recovery, and rollback. Evidence and limits (evidence boundary): Un documento formale può ancora essere una bozza, un release candidate o la versione finale. Controlla il suo stato e il supporto per browser o piattaforma. Unknowns to confirm: Where the code runs, data stores, traffic shape, consistency needs, and the security boundary. Also confirm the compatibility period, service goals, and rollback limits.