OpenAPI-dokumentationscheckliste

Kontrakt som enkelt sandheds kilde

Jeg holder OpenAPI beskrivelsen i samme repository som servicen kode. Dette gør filen synlig for alle, der læser kildekoden, og låser version kontrol viser hver ændring.

Fil placering

Jeg placerer filen i docs/openapi.yaml i repo roden. Stien er kort, let at finde, og kommer ikke i konflikt med genererede aktiver.

Version kontrol praksis

Hver redigering af API kontrakten går gennem en pull anmodning. Jeg kræver mindst en godkender, der checker, om beskrivelsen matcher kode ændringerne. Jeg kører også en lint skridt i CI pipeline før PR kan fusioneres.

Undgå drift med kontrakt tests

Jeg tilføjer en test suite, der kalder den kørende service og validerer hver response mod OpenAPI skemaet. Hvis servicen returnerer noget, der ikke matcher kontrakten, fejler testen og holdet får øjeblikkelig feedback.

- Kontrakten lever ved siden af kode, ikke i en separat wiki - Pull anmodning gennemgang fanger mismatches tidligt - Automatiserede tests beskytter mod runtime drift - Historik viser, hvem ændrede hvad og hvorfor

Fejldokumentation

Integratorer lægger først mærke til problemer, når de modtager en fejl, som de ikke havde forventet. At beskrive 4xx- og 5xx-former reducerer supportbilletter og lader klientgenereringer producere korrekt fejlhåndteringkode.

Definering af 4xx-former

Jeg tilføjer en komponent.svarssektion for hver klientfejl, som API'et kan returnere. Typiske indgange omfatter 400 Bad Request til valideringsproblemer, 401 Unauthorized til manglende eller ugyldige legitimationsoplysninger, 403 Forbidden til utilstrækkelige omfang og 422 Unprocessable Entity til forretningsregelovertrædelser.

Definering af 5xx-former

Serverfejl er mindre hyppige, men kræver alligevel dokumentation. Jeg beskriver en generisk 500 Internal Server Error-svar og, hvor det er relevant, en 503 Service Unavailable med en Retry-After-header.

Eksempel på fejlsvar

- Dokumentér hver enkelt fejlkode, som tjenesten kan udsende - Lever en kort besked og en valgfri detaljerarray - Hold fejlskemaer genbrugelige på tværs af endepunkter - Opdater fejldokumenter, når du tilføjer nye valideringsregler

Eksempler ved siden af skemaer

Når en udvikler ser et klart anmodnings- eller svarseksempel, reduceres den tid, der bruges på at gætte, dramatisk. Jeg placerer eksempler lige ved siden af skemaet, de illustrerer, ved hjælp af OpenAPIs eksempel eller eksempler-felter.

Inline-eksempler

Til simple objekter tilføjer jeg en eksempelværdi inde i skemaet. Dette vises i Swagger UI og Redoc uden ekstra filer.

Eksterne eksempler

Til større payloads holder jeg en separat examples/-mappe og henviser til den med $ref:./examples/payment-request.json. Dette holder hovedfilen læselig, mens det stadig giver rigelige eksempler.

Generering af kodestykker

APIDocGen læser OpenAPI-filen og opretter curl-, JavaScript fetch- og Python requests-kodestykker til hver operation. Jeg gemmer disse kodestykker i docs/snippets/-mappen og linker til dem fra operationsbeskrivelsen.

- Eksempler reducerer frem- og tilbagegang i Slack eller e-mail - Inline-eksempler fungerer godt for små DTOer - Eksterne filer holder hovedspecifikationen pyntelig - Genererede kodestykker giver udviklerne en kopier-og-indryk-startpoint

Lint i CI

En brudt reference eller en manglende operationId kan stille og roligt ødelægge klientgenerering og dokumentationssites. Jeg kører en linter som en del af byggepipeline og afbryder bygningen ved enhver fejl.

Valg af linter

Jeg bruger Spectral med spectral:oas-regelsættet, fordi det forstår OpenAPI 3.1 og lader mig tilføje brugerdefinerede regler for vores interne konventioner.

CI-integrationstrin

I GitHub Actions-workflow tilføjer jeg et trin, der installerer Spectral via npm og derefter kører spectral lint docs/openapi.yaml. Trinet bruger indstillingen continue-on-error: false, så ethvert problem stopper pipeline.

Håndtering af $ref og operationId

Linteren checker, at hver $ref kan løses, og at hver operationId er unik på tværs af filen. Jeg påtvinger også, at alle stier har en summary og en beskrivelse.

Regel | Alvorlighed | Hvad den checker no-unresolved-ref | fejl | Alle $ref-pege skal løses operation-operationId | fejl | Hver operation skal have en operationId no-duplicate-operationId | fejl | operationId-værdier skal være unikke path-summary | advarsel | Hver sti skal have en summary path-description | advarsel | Hver sti skal have en beskrivelse

- Lint-trin kører på hver push og pull-anmodning - Fejl blokerer sammenlægninger, advarsler vises i check-udgang - Brugerdefinerede regler kan påtvinge virksomhedsspecifikke navngivningskonventioner - Udgang er let at læse i GitHub Checks-brugergrænsefladen

Hvad dette ikke er

Jeg vil være ærlig omkring begrænsningerne for en checkliste. At følge disse punkter forbedrer kvaliteten af din OpenAPI-beskrivelse, men det garanterer ikke perfekt dokumentation i alle situationer.

Ikke en garanti for perfekte dokumenter

Selv med en fejlfri fil og rige eksempler, kan udviklere stadig finde huller, hvis API-adfærden ændrer sig ved kørselstidspunktet. Checklisten hjælper dig med at fange mange problemer, men du skal stadig verificere den live-tjeneste.

Ikke en erstatning for runtime-test

Kontrakttest, der validerer svar mod skemaet, er værdifulde, men de erstatter ikke eksplorativ test, performance-test eller sikkerhedsskanning. Behandle checklisten som et lag af forsvar.

Ikke en substitut for god design

Hvis den underliggende API er forvirrende eller inkonsistent, så vil ingen mængde af dokumentation gøre det let at bruge. Brug tid på ren ressource-modellering, klart navngivning og fornuftige fejl-koder, før du investerer tungt i dokumenter.

- Checklisten forbedrer konsistens, ikke korrekthed af forretningslogik - Runtime-overvågning er stadig nødvendig for at fange drift efter installation - God design reducerer mængden af forklarende tekst, der kræves - Behandle dokumentation som en levende artifact, ikke en enkelt opgave

Hold dokumentation opdateret

En OpenAPI-fil kan blive forældet, hvis ingen lægger mærke til, at koden er ændret. Jeg har indført lette vaner, der gør forældede filer synlige, før de forårsager forvirring.

Automatisk generering

Jeg konfigurerer CI-pipeline til at regenerere HTML-dokumentation (ved hjælp af Redoc) efter hver succesfuld build og offentliggør outputtet på en statisk website-vært. URL'en for de offentliggjorte dokumenter vises i pull-anmodningens kommentar, så anmelderne kan se den renderede version med det samme.

Gennemgangsprocessen

Hver gang en bidrager ændrer en handler eller en datamodel, beder jeg dem om at åbne OpenAPI-filen og verificere, at de relevante stier, parametre og svar reflekterer ændringen. Jeg tilføjer en påmindelsekommentar i pull-anmodningsskabelonen.

Overvågning af forældede filer

Jeg kører en natlig job, der git-diff'er OpenAPI-filen mod versionen fra den foregående uge. Hvis diff'en viser mere end tredive ændrede linjer, poster jobbet en besked til teamkanalen og beder om en hurtig gennemgang.

- Offentliggjorte dokumenter giver en visuel cue om, at kildekoden er aktuel - Gennemgangspåmindelser holder kontrakten tæt på koden - Automatisk diff fremhæver store, uventede redigeringer - Alle trin køres uden manuel indgriben

Operatør checklist for OpenAPI-dokumentation (2026)

Jeg holder en skrevet checklist ved hver udgivelse, der berører dette emne. Listen er kedelig med vilje: navngiv ejeren, navngiv bevisartefakten og navngiv rollback. Hvis et trin ikke kan producere en fil, en ticket eller en loglinje, er det ikke et trin - det er en ønsketænkning.

Før du ændrer produktion

- Fryse branchen eller konfigurationsrevisionen, du vil måle imod. - Optegn den nuværende fejltilstand med en konkret indgang og en konkret udgang. - Bekræft, hvilken identitet jobbet kører som, og om denne identitet kan nå data, den ikke skal kunne nå. - Åbn de primære referencer, du vil citerer: https://learn.openapis.org/best-practices.html, https://redocly.com/docs/redoc.

Mens du kører checken

- Foretræk en reproducerbar vej over ti anekdotiske skærmbilleder. - Skriv den forventede sikre udfald, før du udløser værktøjet eller forespørgslen. - Fanget det eksakte kommando, prompt, skema eller regex under test - ikke en paraphrase. - Hvis systemet kan handle (sende, skrive, slette, overføre), kræv en bekræftelsesgrænse i samme pass.

Efter du er færdig

- Fil residual risiko med en ejer og en dato, selvom scan er ren. - Konverter ikke en grøn check til salgsprosa, der hævder fuldstændighed. - Kør den samme checklist, når modellen, værktøjet, skemaet eller valideringsreglerne ændres.

Signal | Hvad at optegne | Stop-ship? Uventet skriv eller send | Værktøjsnavn, args, identitet | Ja, indtil gated Manglende bekræftelse på destruktiv handling | Call-sti og omgåelse | Ja Ubetroet tekst behandlet som instruktion | Kildeoverflade og resulterende handling | Ja for agent-rækkevidde Scanner ren, dommer åben | Udsatte elementer + ejer | Kun hvis kerne-sti er sikker

APIDocGen hjælper med den målbare første passering. Arkitekturvalg, juridisk godkendelse og kundeorienterede krav har stadig brug for en menneskelig ejer. Behandle hver checklist-række som beslutningsstøtte, ikke som et certifikat.

Hvordan jeg forklarer begrænsninger for købere

Når en interessent spørger, om produktet "dækker alt", svarer jeg med grænsen: automatiserede kontroller fanger kendte mønstre, men nye kæder og politikdom stiller krav om gennemgang. Den ærlighed holder supportbelastningen nede og holder bloggen aligneret med, hvad produktet faktisk kan.

Hvis du har brug for en anden mening, par denne skrivelse med referencerne nedenfor og med din egen reproduktion i staging. Spring ikke reproductionstrinet over, bare fordi en model skrev en selvbevidst sammenfatning.

Referencer

- https://learn.openapis.org/best-practices.html - https://redocly.com/docs/redoc - https://spec.openapis.org/oas/latest.html - https://spec.openapis.org/oas/latest.html#schema-object