{"canonical_url":"https://engineer.company/da/glossary/openapi/","content_markdown":"# OpenAPI\n\n## Hvad det er\n\nOpenAPI er et standardformat til at skrive alt det ned, en kalder skal vide om et HTTP-API —\nadresser, operationer, input, output, fejl og sikkerhed — i én JSON- eller YAML-fil, som mennesker\nog programmer læser på lige fod. Selve standarden hedder OpenAPI Specification, ofte forkortet\nOAS, og en fil skrevet efter den er en OpenAPI-beskrivelse. Formatet begyndte som Swagger\nSpecification, og det ældre navn lever videre i værktøjer bygget omkring det, som Swagger UI.\n\nSpecifikationen kalder sig selv en programmeringssprogsuafhængig grænsefladebeskrivelse for\nHTTP-API'er. Målet, den sætter sig, er, at et menneske eller et program kan forstå, hvad en\ntjeneste gør, uden kildekoden, ekstra dokumentation eller en optagelse af dens netværkstrafik.\nHoveddokumentet anbefales navngivet `openapi.json` eller `openapi.yaml`, og større beskrivelser\ndeles ofte over flere filer, der er bundet sammen med referencer.\n\nHistorien går gennem én overdragelse. Swagger 2.0 udkom i september 2014 og blev doneret til\nOpenAPI Initiative den 31. december 2015. Version 3.0.0 fulgte i juli 2017 under det nye navn,\n3.1.0 i februar 2021 og 3.2.0 i september 2025.\n\nEn beskrivelse har en håndfuld dele på øverste niveau. `info` navngiver API'et og dets version;\n`servers` angiver, hvor det kører; `paths` rummer hver adresse og under den én operation pr.\nHTTP-metode med dens parametre, request body og mulige svar. `components` samler det, der\ngenbruges: dataskemaer, parametre, svar og de sikkerhedsskemaer, der fortæller, hvordan en kalder\nautentificerer sig. Fra 3.1 kan en `webhooks`-sektion også beskrive de forespørgsler, API'et selv\nsender til sine brugere. Et minimalt udsnit:\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\nDataformerne skrives i et skemasprog. Fra 3.1 er Schema Object et supersæt af JSON Schema Draft\n2020-12; 3.0 brugte en udvidet delmængde af et ældre udkast med egne tilføjelser. JSON Schema\nbeskriver ét stykke data, mens OpenAPI beskriver et helt HTTP-API og låner JSON Schema til\nstykkerne. Naboerne beskriver andre slags grænseflader: AsyncAPI dækker beskedbaserede systemer,\ngRPC-tjenester erklæres i [Protocol Buffers](https://protobuf.dev/)-filer med endelsen `.proto`, og en GraphQL-server\nudgiver sit eget skema.\n\n## Hvorfor det betyder noget\n\nEn beskrivelse i et standardformat er én fil, som mange værktøjer kan læse, og hvert af dem sparer\net stykke arbejde, et team ellers ville gøre i hånden. Referencedokumentationen renderes ud fra\nden. Klientbiblioteker i flere sprog genereres ud fra den, så en frontend kalder en typet funktion\ni stedet for at stykke en URL sammen. Mockservere svarer ud fra den, så en frontend kan bygges,\nfør backenden findes. Gateways importerer ruter fra den, testsuiter validerer trafik mod den, og\nAI-agenter, der kalder API'er, læser den for at se, hvad der bliver tilbudt.\n\nDen rækkevidde er også risikoen. Hvert eneste af de værktøjer stoler på filen. En forkert\nbeskrivelse er værre end ingen, for den genererede klient kompilerer, dokumentationen ser\nautoritativ ud, og fejlen viser sig først i drift, i en andens produkt.\n\nHovedbeslutningen er derfor, hvor beskrivelsen kommer fra. I design-first-arbejde skriver folk\nbeskrivelsen, reviewer den som kontrakten og bygger derefter serveren, så den passer. API'ets form\nbliver diskuteret, før der findes kode, hvilket passer til offentlige API'er og til teams, der\narbejder parallelt. Prisen er, at beskrivelsen og serveren er to ting, der kan blive uenige. I\ncode-first-arbejde genereres beskrivelsen ud fra serverens egne typer og annotationer. Den kan\nikke beskrive en rute, serveren mangler, men den er kun så præcis som de typer, og\ndesigndiskussionen foregår i code review i stedet for i et dokument. Uanset vejen forbliver\nbeskrivelsen kun sand, hvis et build tjekker den.\n\nVersioner betyder mere, end de ser ud til. Skiftet fra 3.0 til 3.1 ændrede, hvordan skemaobjekter\nskrives, fordi 3.1 tog JSON Schema 2020-12 til sig. Generatorer, validatorer og gateways\nunderstøtter hver deres udsnit af versioner, så den version, et team skriver i, er begrænset af det\nældste værktøj i kæden.\n\n## Sådan ser det ud i praksis\n\nEt API på Fiber begyndte med validering skrevet i hånden, endpoint for endpoint, og uden et samlet\ndokument over dets form.\n[HTTP-laget flyttede til Huma v2](/da/portfolio/migrated-the-api-to-huma-v2-at-100-parity/), oven\npå Fiber, så hvert endpoint erklæres med input- og output-structs, og OpenAPI-beskrivelsen genereres\nud fra de typer; dokumentationen holder trit med koden i stedet for at forældes i en wiki. De to\nWebSocket-endpoints bliver på rå Fiber, uden for Humas model med forespørgsel og svar. Siden siger\nligeud, hvorfor skalaen tæller: ved 760 operationer fordelt på 649 paths er beskrivelsen i praksis\ndet eneste sted, nogen kan læse API'et, så vished om, at den er komplet, vejer tungere, end den\ngjorde ved halvtreds. Et tjek i CI holder pariteten mellem ruter og beskrivelse på 100 %.\n\nBeskrivelsen kan også være det midterste led i en kæde, der løber fra databasen og udad. Skemaet og\ndets funktioner former Go-typerne,\n[Huma udsender beskrivelsen, og det, frontenden bruger, genereres ud fra den](/da/portfolio/generated-the-api-contract-from-the-database-out/):\nen typet TypeScript-klient på 44.076 linjer, 61 mock-handlere til frontendens tests og de grænser,\nhver formular håndhæver. Det modvirker, at frontend og backend glider fra hinanden, som typisk viser sig som et\n422 i browseren, efter at uoverensstemmelsen er sendt ud. Et kontrakttjek i CI får buildet til at\nfejle ved afvigelse og kigger særligt efter i valgfrie felter i request body, hvor »mangler« og\n»null« bliver forvekslet, og i enums for query-parametre. Siden nævner også prisen: et\ngenereringstrin midt i det hele og en kæde, der kun er så pålidelig som sit svagest bevogtede led.\n\n[Virksomhedens side om parathed til AI-agenter](/da/ai-ready/) bruger samme tankegang over for\nagenter. En applikation, som agenter kan bruge, tilbyder et beskrevet API: et OpenAPI-dokument, en\nMCP-server, hvor agenter skal kalde applikationen direkte, og OAuth-metadata, så en agent kan\nhandle på vegne af en bruger, uden at nogen giver sin adgangskode fra sig. Siden klassificerer\nhver anbefaling til agenter i stedet for blot at følge den, og fordi virksomhedens eget site ikke\nhar noget API, er et API-katalog og OAuth-metadata to af de fem, der blev valgt fra dér.\n\n## Hvor det går galt\n\n**Beskrivelsen lover noget, serveren ikke gør.** En beskrivelse, der vedligeholdes i hånden,\nsakker bagud: en ny query-parameter, et omdøbt felt eller en fejlkode, som kun serveren kender\ntil. Genererede klienter kompilerer så mod en fiktion. Generér beskrivelsen ud fra koden, eller\nhold den adskilt og validér rigtige forespørgsler og svar mod den i testsuiten, og sammenlign de\nruter, serveren registrerer, med de paths, beskrivelsen opregner.\n\n**Hver regenerering af klienten omdøber halvdelen af metoderne.** Uden et `operationId` finder\ngeneratorerne selv på metodenavne ud fra stien og HTTP-metoden, så når en rute flytter, skifter\nden funktion, som alle kaldere bruger, navn. Specifikationen kræver, at hvert `operationId` er\nunikt, og skelner mellem store og små bogstaver i det. Sæt et på hver operation, vælg det lige så\nomhyggeligt som navnet på en offentlig funktion, og lad en linter få buildet til at fejle, når et\nmangler.\n\n**Felter, der må være null, begynder at afvise null efter en opgradering.** OpenAPI 3.0 markerede\ndem med `nullable: true`. I 3.1 er det nøgleord væk, og typen bliver en liste, og en validator,\nder møder et nøgleord, den ikke kender, springer det som regel over. Et 3.0-skema, der blot får\npåskriften 3.1, afviser derfor null alle de steder, forfatteren ville tillade det. Konvertér\nskemaerne efter OpenAPI Initiatives opgraderingsguide, som også dækker, at `exclusiveMinimum`\nbliver et tal:\n\n```yaml\n# OpenAPI 3.0\ntype: string\nnullable: true\n---\n# OpenAPI 3.1\ntype: [string, \"null\"]\n```\n\n**Eksemplerne består ikke deres eget skema.** Specifikationen siger, at et eksempel bør matche sit\nskema, og overlader kontrollen til værktøjerne. En læser kopierer eksemplet fra dokumentationen og\nfår et 422; en mockserver serverer det, og frontenden bliver bygget mod data, som det rigtige API\nvil afvise. Validér hvert eksempel i CI, lige så strengt som rigtig trafik.\n\n**Den offentlige beskrivelse kortlægger admin-API'et.** Én beskrivelse genereret ud fra alle ruter\nog serveret på en offentlig adresse viser interne operationer og deres skemaobjekter til enhver, der\nspørger. Udgiv én beskrivelse pr. publikum, genereret med de interne operationer filtreret fra.\nSpecifikationen tillader, at objekter står tomme eller fjernes netop til den slags adgangskontrol.\n\n## Læs mere\n\n- [OpenAPI Specification](https://spec.openapis.org/oas/latest.html) — den seneste version af\n  standarden med hvert objekt og felt defineret og en historik over hver udgivelse.\n- [JSON Schema Draft 2020-12](https://json-schema.org/draft/2020-12) — det skemasprog, OpenAPI 3.1\n  og senere bruger til hver request- og response-body.\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 skemaændringer, med `nullable` iblandt.\n- [Huma: OpenAPI Generation](https://huma.rocks/features/openapi-generation/) — hvordan\n  Go-frameworket fra projekterne ovenfor udleder en beskrivelse af handlernes typer.\n\n\u003chttps://engineer.company/da/glossary/openapi/\u003e\n","date_modified":"2026-11-12T05:34:23Z","description":"Hvad OpenAPI er, hvordan én fil kan drive dokumentation, klienter og mocks, hvad det koster at holde den sand, og de fejl, der får den til at glide.","formats":{"gemtext":"https://engineer.company/da/glossary/openapi/index.gmi","gopher":"https://engineer.company/da/glossary/openapi/gophermap","html":"https://engineer.company/da/glossary/openapi/","json":"https://engineer.company/da/glossary/openapi/index.json","markdown":"https://engineer.company/da/glossary/openapi/index.md","pdf":"https://engineer.company/da/glossary/openapi/index.pdf"},"kind":"page","language":"da","title":"Hvad er OpenAPI?","url":"https://engineer.company/da/glossary/openapi/","version":1}