{"canonical_url":"https://engineer.company/nb/glossary/openapi/","content_markdown":"# OpenAPI\n\n## Hva det er\n\nOpenAPI er et standardformat for å skrive ned alt den som kaller et HTTP-API, trenger å\nvite – adresser, operasjoner, inndata, utdata, feil og sikkerhet – i én JSON- eller\nYAML-fil som både mennesker og programmer kan lese. Selve standarden heter OpenAPI\nSpecification, ofte forkortet OAS, og en fil skrevet etter den kalles en\nOpenAPI-beskrivelse. Formatet startet som Swagger Specification, og det eldre navnet\nlever videre i verktøy bygd rundt det, f.eks. Swagger UI.\n\nSpesifikasjonen beskriver seg selv som en grensesnittbeskrivelse for HTTP-API-er som er\nuavhengig av programmeringsspråk. Målet den oppgir, er at en person eller et program\nskal kunne forstå hva en tjeneste gjør, uten kildekoden, uten ekstra dokumentasjon og\nuten å fange opp nettverkstrafikken. Inngangsdokumentet anbefales navngitt\n`openapi.json` eller `openapi.yaml`, og større beskrivelser deles ofte opp i flere filer\nsom henger sammen gjennom referanser.\n\nSwagger 2.0 kom i september 2014 og ble gitt til OpenAPI Initiative 31. desember 2015.\nVersjon 3.0.0 fulgte i juli 2017 under det nye navnet, 3.1.0 i februar 2021 og 3.2.0 i\nseptember 2025.\n\nEn beskrivelse har en håndfull deler på øverste nivå. `info` navngir API-et og\nversjonen; `servers` lister hvor det kjører; `paths` inneholder hver adresse og, under\nden, én operasjon per HTTP-metode, med parametere, forespørselskropp og mulige svar.\n`components` samler det som gjenbrukes: dataskjemaer, parametere, svar og\nsikkerhetsordningene (security schemes) som sier hvordan den som kaller, autentiserer\nseg. Fra og med 3.1 kan en egen `webhooks`-del også beskrive forespørsler API-et sender\ntil sine brukere. Et minimalt utdrag:\n\n```yaml\nopenapi: 3.1.0\ninfo:\n    title: Orders\n    version: 1.4.0\npaths:\n    /orders/{id}:\n        get:\n            operationId: getOrder\n            parameters:\n                - name: id\n                  in: path\n                  required: true\n                  schema:\n                      type: string\n            responses:\n                \"200\":\n                    description: One order\n```\n\nDataformene skrives i et skjemaspråk. Fra 3.1 er Schema Object en overmengde av JSON\nSchema Draft 2020-12; 3.0 brukte en utvidet delmengde av et eldre utkast, med egne\ntillegg. JSON Schema beskriver ett enkelt dataelement, mens OpenAPI beskriver et helt\nHTTP-API og låner JSON Schema til bitene. Naboene beskriver andre typer grensesnitt:\nAsyncAPI dekker meldingsdrevne systemer, gRPC-tjenester deklareres i `.proto`-filer for\n[Protocol Buffers](https://protobuf.dev/), og en GraphQL-server publiserer sitt eget skjema.\n\n## Hvorfor det er viktig\n\nEn beskrivelse i et standardformat er én fil som mange verktøy kan lese, og hvert av dem\nsparer et team for arbeid det ellers ville gjort for hånd. Referansedokumentasjonen\ngjengis fra den. Klientbiblioteker i flere språk genereres fra den, så en frontend\nkaller en typet funksjon i stedet for å sette sammen en URL. Mock-servere svarer ut fra\nden, så frontenden kan bygges før backenden finnes. API-gatewayer importerer ruter fra\nden, testsuiter validerer trafikk mot den, og AI-agenter som kaller API-er, leser den\nfor å finne ut hva som tilbys.\n\nDen rekkevidden er også risikoen. Hvert eneste av disse verktøyene stoler på filen. En\nbeskrivelse som er feil, er verre enn ingen, fordi den genererte klienten kompilerer,\ndokumentasjonen ser autoritativ ut, og feilen dukker opp under kjøring i noen andres\nprodukt.\n\nDen viktigste beslutningen er derfor hvor beskrivelsen kommer fra. Ved design-first\nskriver folk beskrivelsen, gjennomgår den som kontrakten og bygger deretter serveren\nslik at den stemmer. Formen på API-et diskuteres før det finnes kode, og det passer for\noffentlige API-er og for team som jobber parallelt. Prisen er at beskrivelsen og\nserveren er to ting som kan være uenige. Ved code-first genereres beskrivelsen fra\nserverens egne typer og annotasjoner. Den kan ikke beskrive en rute serveren ikke har,\nmen den er aldri mer presis enn de typene, og designdiskusjonen skjer i\nkodegjennomgangen i stedet for i et dokument. Uansett holder beskrivelsen seg sann bare\nhvis et bygg kontrollerer den.\n\nOvergangen fra 3.0 til 3.1 endret hvordan dataskjemaer skrives, fordi 3.1 tok i bruk\nJSON Schema 2020-12. Generatorer, validatorer og gatewayer støtter hver sitt utvalg av\nversjoner, så versjonen et team skriver i, begrenses av det eldste verktøyet i kjeden.\n\n## Slik ser det ut i praksis\n\nPå én plattform startet API-et på Fiber, med validering skrevet for hånd, endepunkt for\nendepunkt, og uten noe samlet dokument som beskrev formen. Så ble\n[HTTP-laget flyttet over på Huma v2](/nb/portfolio/migrated-the-api-to-huma-v2-at-100-parity/),\noppå Fiber, slik at hvert endepunkt deklareres med struct-typer for inndata og utdata,\nog OpenAPI-beskrivelsen genereres fra de typene. Dokumentasjonen følger koden i stedet\nfor å forfalle i en wiki. De to WebSocket-endepunktene ble igjen på ren Fiber, utenfor\nforespørsel/svar-modellen til Huma. Siden forklarer hvorfor størrelsen betyr noe: med\n760 operasjoner fordelt på 649 stier er beskrivelsen i praksis den eneste måten noen kan\nlese API-et på, så det å vite at den er fullstendig, betyr mer enn det gjorde ved femti.\nEn kontroll i CI holder samsvaret mellom rutene og beskrivelsen på 100 %.\n\nPå en annen plattform er beskrivelsen det midterste leddet i en kjede som går fra\ndatabasen og utover. Databaseskjemaet og funksjonene i det former Go-typene,\n[Huma lager beskrivelsen, og det frontenden bruker, genereres fra den](/nb/portfolio/generated-the-api-contract-from-the-database-out/):\nen typet TypeScript-klient på 44 076 linjer, 61 mock-handlere for frontendens tester og\ngrensene hvert webskjema håndhever. Den løser avvik mellom frontend og backend, som\nellers gjerne viser seg som en 422 i nettleseren etter at avviket er levert. En\nkontraktskontroll i CI får bygget til å feile ved avvik, med en probe rettet mot\nvalgfrie felt i forespørselskroppen, der «mangler» og «null» blandes sammen, og mot\nenumer i spørringsparametere. Siden sier rett ut hva det koster: et genereringstrinn\nmidt i alt sammen, og en kjede som bare er så pålitelig som sitt dårligst bevoktede\nledd.\n\n[Selskapets side om å være klar for AI-agenter](/nb/ai-ready/) bruker det samme\nresonnementet på agenter. En app som agenter kan bruke, tilbyr et beskrevet API: et\nOpenAPI-dokument, en MCP-server der agenter bør kalle det direkte, og OAuth-metadata, så\nen agent kan handle på vegne av en bruker uten å få passordet. Siden klassifiserer hver\nanbefaling i stedet for å følge den blindt, og fordi selskapets eget nettsted ikke har\nnoe API, er en API-katalog og OAuth-metadata to av de fem den takket nei til der.\n\n## Hvor det går galt\n\n**Beskrivelsen lover noe serveren ikke gjør.** En beskrivelse som vedlikeholdes for\nhånd, sakker akterut: en ny spørringsparameter, et felt med nytt navn eller en feilkode\nsom bare serveren kjenner til. Genererte klienter kompilerer da mot en fiksjon. Generer\nbeskrivelsen fra koden, eller hold den adskilt og valider ekte forespørsler og svar mot\nden i testsuiten, og sammenlign rutene serveren registrerer, med stiene beskrivelsen\nlister opp.\n\n**Hver ny generering av klienten gir halvparten av metodene nye navn.** Uten en\n`operationId` finner generatorene på metodenavn ut fra stien og HTTP-metoden, så når en\nrute flyttes, får funksjonen alle kallerne bruker, nytt navn. Spesifikasjonen krever at\nhver `operationId` er unik, og skiller mellom store og små bokstaver. Sett en på hver\noperasjon, velg den like nøye som navnet på en offentlig funksjon, og la en linter\nstoppe bygget når den mangler.\n\n**Felt som kan være null, begynner å avvise null etter en oppgradering.** OpenAPI 3.0\nmerket dem med `nullable: true`. I 3.1 er det nøkkelordet borte, og typen blir en liste,\nog en validator som møter et nøkkelord den ikke kjenner, ignorerer det som regel. Et\n3.0-skjema som bare merkes om til 3.1, avviser derfor null overalt der forfatteren ville\ntillate det. Konverter dataskjemaene med oppgraderingsveiledningen fra OpenAPI\nInitiative, som også dekker at `exclusiveMinimum` blir et tall:\n\n```yaml\n# OpenAPI 3.0\ntype: string\nnullable: true\n---\n# OpenAPI 3.1\ntype: [string, \"null\"]\n```\n\n**Eksemplene består ikke sitt eget skjema.** Spesifikasjonen sier at et eksempel bør\nstemme med skjemaet sitt, og overlater kontrollen til verktøyene. En leser kopierer\neksempelet fra dokumentasjonen og får en 422; en mock-server serverer det, og frontenden\nbygges mot data det ekte API-et kommer til å avvise. Valider hvert eksempel i CI, like\nstrengt som ekte trafikk.\n\n**Den offentlige beskrivelsen kartlegger admin-API-et.** Én beskrivelse generert fra\nalle ruter og servert på en offentlig adresse viser interne operasjoner og dataskjemaene\nderes til alle som spør. Publiser én beskrivelse per målgruppe, generert med de interne\noperasjonene filtrert bort. Spesifikasjonen tillater at objekter står tomme eller\nfjernes nettopp for denne typen tilgangskontroll.\n\n## Les mer\n\n- [OpenAPI Specification](https://spec.openapis.org/oas/latest.html) — siste versjon av\n  standarden, med hvert objekt og felt definert og historikken for hver utgave.\n- [JSON Schema Draft 2020-12](https://json-schema.org/draft/2020-12) — skjemaspråket\n  OpenAPI 3.1 og senere bruker for hver forespørselskropp og hvert svar.\n- [Upgrading from OpenAPI 3.0 to 3.1](https://learn.openapis.org/upgrading/v3.0-to-v3.1.html)\n  — OpenAPI Initiatives egen liste over endringer i dataskjemaene, `nullable` blant dem.\n- [Huma: OpenAPI Generation](https://huma.rocks/features/openapi-generation/) — hvordan\n  Go-rammeverket fra prosjektene over avleder en beskrivelse fra typene til handlerne.\n\n\u003chttps://engineer.company/nb/glossary/openapi/\u003e\n","date_modified":"2026-11-12T05:34:23Z","description":"OpenAPI-beskrivelsen som kontrakt: hva én fil kan generere, design-first mot code-first, og feilene som får fil og server til å gli fra hverandre.","formats":{"gemtext":"https://engineer.company/nb/glossary/openapi/index.gmi","gopher":"https://engineer.company/nb/glossary/openapi/gophermap","html":"https://engineer.company/nb/glossary/openapi/","json":"https://engineer.company/nb/glossary/openapi/index.json","markdown":"https://engineer.company/nb/glossary/openapi/index.md","pdf":"https://engineer.company/nb/glossary/openapi/index.pdf"},"kind":"page","language":"nb","title":"Hva er OpenAPI?","url":"https://engineer.company/nb/glossary/openapi/","version":1}