{"canonical_url":"https://engineer.company/sv/glossary/openapi/","content_markdown":"# OpenAPI\n\n## Vad det är\n\nOpenAPI är ett standardformat för att skriva ner allt som en anropare behöver veta om ett HTTP-API —\nadresser, operationer, indata, utdata, fel och säkerhetskrav — i ett enda JSON- eller YAML-dokument\nsom människor och program läser på samma sätt. Själva standarden heter OpenAPI Specification, ofta\nförkortad OAS, och ett dokument skrivet enligt den kallas en OpenAPI-beskrivning. Formatet började\nsom Swagger Specification, och det äldre namnet lever kvar i verktyg som byggts kring det, till\nexempel Swagger UI.\n\nSpecifikationen beskriver sig själv som en gränssnittsbeskrivning för HTTP-API:er som är oberoende\nav programspråk. Målet den anger är att en människa eller ett program ska kunna förstå vad en tjänst\ngör utan dess källkod, ytterligare dokumentation eller en inspelning av dess nätverkstrafik.\nRotdokumentet rekommenderas heta `openapi.json` eller `openapi.yaml`, och större beskrivningar delas\nofta upp i flera dokument som fogas samman med referenser.\n\nSwagger 2.0 släpptes i september 2014 och skänktes till OpenAPI Initiative den 31 december 2015.\nVersion 3.0.0 kom i juli 2017 under det nya namnet, följd av 3.1.0 i februari 2021 och 3.2.0 i\nseptember 2025.\n\nEn beskrivning har en handfull delar på toppnivå. `info` namnger API:et och dess version; `servers`\nlistar var det körs; `paths` innehåller varje adress och, under den, en operation per HTTP-metod,\nmed parametrar, anropets body och möjliga svar. `components` samlar det som återanvänds:\ndatascheman, parametrar, svar och de säkerhetsscheman som anger hur en anropare autentiserar sig.\nSedan 3.1 kan en sektion `webhooks` dessutom beskriva anrop som API:et skickar till sina\nkonsumenter. Ett 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\nDatastrukturerna skrivs i ett schemaspråk. Från och med 3.1 är Schema Object en övermängd av JSON\nSchema Draft 2020-12; 3.0 använde en utökad delmängd av ett äldre utkast med egna tillägg. JSON\nSchema beskriver ett enskilt dataobjekt, medan OpenAPI beskriver ett helt HTTP-API och lånar JSON\nSchema för delarna. Grannarna beskriver andra slags gränssnitt: AsyncAPI täcker meddelandedrivna\nsystem, gRPC-tjänster deklareras med [Protocol Buffers](https://protobuf.dev/) i `.proto`-definitioner, och en GraphQL-tjänst\npublicerar sitt eget schema.\n\n## Varför det spelar roll\n\nEn beskrivning i ett standardformat är ett enda dokument som många verktyg kan läsa, och vart och\nett sparar arbete som ett team annars hade fått göra för hand. Referensdokumentationen renderas från\nden. Klientbibliotek i flera språk genereras från den, så att en frontend anropar en typad funktion\ni stället för att sätta ihop en URL. Mockservrar svarar utifrån den, så att en frontend kan byggas\ninnan backend finns. API-gateways importerar rutter från den, testsviter validerar trafik mot den,\noch AI-agenter som anropar API:er läser den för att se vad som erbjuds.\n\nDen räckvidden är också risken. Vart och ett av verktygen litar på dokumentet. En beskrivning som är\nfel är värre än ingen alls, eftersom den genererade klienten kompilerar, dokumentationen ser\nauktoritativ ut och misstaget visar sig vid körning i någon annans produkt.\n\nDet viktigaste beslutet gäller därför var beskrivningen kommer ifrån. Vid design-first skriver\nmänniskor beskrivningen, granskar den som kontraktet och bygger sedan servern så att den stämmer.\nAPI:ets form diskuteras innan det finns någon kod, vilket passar publika API:er och team som arbetar\nparallellt. Priset är att beskrivningen och servern är två saker som kan säga emot varandra. Vid\ncode-first genereras beskrivningen från serverns egna typer och annoteringar. Den kan inte beskriva\nen rutt som servern saknar, men den är bara så exakt som typerna, och designdiskussionen sker i\nkodgranskningen i stället för i ett dokument. Hur man än gör förblir beskrivningen sann bara om ett\nbygge kontrollerar den.\n\nSteget från 3.0 till 3.1 ändrade hur schemadelen skrivs, eftersom 3.1 tog över JSON Schema 2020-12.\nGeneratorer, validerare och gateways stöder var och en sitt eget spann av versioner, så den version\nett team skriver begränsas av det äldsta verktyget i kedjan.\n\n## Så ser det ut i praktiken\n\nEn OpenAPI-beskrivning kan vara dokumentation som följer koden eller en länk i en kedja som\ngenererar kod, och arbetet här har gett den båda uppgifterna.\n\nPå en plattform började API:et på Fiber med validering skriven för hand, slutpunkt för slutpunkt,\noch utan något samlat dokument som beskrev dess form.\n[HTTP-lagret flyttades till Huma v2](/sv/portfolio/migrated-the-api-to-huma-v2-at-100-parity/),\novanpå Fiber, så varje slutpunkt deklareras med structar för indata och utdata och\nOpenAPI-beskrivningen genereras från de typerna; dokumentationen följer koden i stället för att\nåldras i en wiki. De två slutpunkterna för WebSocket ligger kvar på ren Fiber, utanför den modell\nmed anrop och svar som Huma bygger på. Sidan förklarar varför skalan spelar roll: med 760\noperationer fördelade på 649 sökvägar är beskrivningen i praktiken det enda sätt som någon kan läsa\nAPI:et på, så vetskapen om att den är komplett väger tyngre än vid femtio. En kontroll i CI håller\npariteten mellan rutter och beskrivning på 100 %.\n\nPå en annan plattform är beskrivningen mittlänken i en kedja som går från databasen och utåt.\nSchemat och dess funktioner formar Go-typerna,\n[Huma genererar beskrivningen, och det som frontenden använder genereras från den](/sv/portfolio/generated-the-api-contract-from-the-database-out/):\nen typad TypeScript-klient på 44 076 rader, 61 mock-hanterare för frontendens tester och de gränser\nsom varje formulär upprätthåller. Den motverkar att frontend och backend glider isär, som oftast\nvisar sig som en 422 i webbläsaren efter att avvikelsen redan har släppts. En kontraktskontroll i CI\nfäller bygget vid avvikelse, med en sond riktad mot valfria fält i anropets body, där ”saknas” och\n”null” blandas ihop, och mot enum-värden i query-parametrar. Sidan sätter namn på priset: ett\ngenereringssteg mitt i allt, och en kedja som bara är så pålitlig som sin sämst skyddade länk.\n\n[Företagets sida om att vara redo för AI-agenter](/sv/ai-ready/) tillämpar samma resonemang på\nagenter. En applikation som agenter kan använda erbjuder ett beskrivet API: ett OpenAPI-dokument, en\nMCP-server där agenter ska anropa det direkt, och OAuth-metadata så att en agent kan agera för en\nanvändare utan att få lösenordet. Sidan klassificerar varje rekommendation i stället för att lyda\nden, och eftersom företagets egen webbplats saknar API är en API-katalog och OAuth-metadata två av\nde fem som valdes bort där.\n\n## Var det går fel\n\n**Beskrivningen lovar något som servern inte gör.** En handskött beskrivning halkar efter: en ny\nquery-parameter, ett omdöpt fält eller en felkod som bara servern känner till. Genererade klienter\nkompilerar då mot en fiktion. Generera beskrivningen från koden, eller håll den separat och validera\nverkliga anrop och svar mot den i testsviten, och jämför de rutter som servern registrerar med de\nsökvägar som beskrivningen listar.\n\n**Varje omgenerering av klienten döper om hälften av metoderna.** Utan `operationId` hittar\ngeneratorer på metodnamn utifrån sökvägen och HTTP-metoden, så att en flyttad rutt döper om den\nfunktion som varje anropare använder. Specifikationen kräver att varje `operationId` är unikt och\nskiljer på stora och små bokstäver. Sätt ett på varje operation, välj det lika omsorgsfullt som\nnamnet på en publik funktion, och låt en linter fälla bygget när ett saknas.\n\n**Fält som får vara null börjar avvisa null efter en uppgradering.** OpenAPI 3.0 markerade dem med\n`nullable: true`. I 3.1 är det nyckelordet borta och typen blir en lista, och en validerare som\nstöter på ett nyckelord den inte känner igen brukar ignorera det. Ett schema för 3.0 som bara märks\nom till 3.1 avvisar därför null överallt där författaren menade att tillåta det. Konvertera med\nuppgraderingsguiden från OpenAPI Initiative, som också tar upp att `exclusiveMinimum` blir ett tal:\n\n```yaml\n# OpenAPI 3.0\ntype: string\nnullable: true\n---\n# OpenAPI 3.1\ntype: [string, \"null\"]\n```\n\n**Exemplen klarar inte sitt eget schema.** Specifikationen säger att ett exempel ska stämma med sitt\nschema och lämnar kontrollen åt verktygen. En läsare kopierar exemplet ur dokumentationen och får en\n422; en mockserver serverar det, och frontenden byggs mot data som det verkliga API:et kommer att\navvisa. Validera varje exempel i CI, lika strikt som skarp trafik.\n\n**Den publika beskrivningen kartlägger admin-API:et.** En beskrivning som genereras från varje rutt\noch serveras på en publik adress visar interna operationer och deras datastrukturer för vem som\nhelst som frågar. Publicera en beskrivning per målgrupp, genererad med de interna operationerna\nbortfiltrerade. Specifikationen tillåter att objekt lämnas tomma eller tas bort för just den här\nsortens åtkomstkontroll.\n\n## Läs mer\n\n- [OpenAPI Specification](https://spec.openapis.org/oas/latest.html) — den senaste versionen av\n  standarden, med varje objekt och fält definierat och en historik över varje utgåva.\n- [JSON Schema Draft 2020-12](https://json-schema.org/draft/2020-12) — schemaspråket som OpenAPI 3.1\n  och senare använder för varje body i anrop och svar.\n- [Upgrading from OpenAPI 3.0 to 3.1](https://learn.openapis.org/upgrading/v3.0-to-v3.1.html) —\n  listan från OpenAPI Initiative över ändringar i schemadelen, `nullable` bland dem.\n- [Huma: OpenAPI Generation](https://huma.rocks/features/openapi-generation/) — hur Go-ramverket som\n  används i projekten ovan härleder en beskrivning ur typerna i hanterarna.\n\n\u003chttps://engineer.company/sv/glossary/openapi/\u003e\n","date_modified":"2026-11-12T05:34:23Z","description":"Vad OpenAPI är, hur ett enda dokument kan driva dokumentation, klienter och mockar, vad det kostar att hålla det sant och misstagen som låter det glida isär.","formats":{"gemtext":"https://engineer.company/sv/glossary/openapi/index.gmi","gopher":"https://engineer.company/sv/glossary/openapi/gophermap","html":"https://engineer.company/sv/glossary/openapi/","json":"https://engineer.company/sv/glossary/openapi/index.json","markdown":"https://engineer.company/sv/glossary/openapi/index.md","pdf":"https://engineer.company/sv/glossary/openapi/index.pdf"},"kind":"page","language":"sv","title":"Vad är OpenAPI?","url":"https://engineer.company/sv/glossary/openapi/","version":1}