API-dokumentation på svenska: verktyg, standard och best practice

En bra API-dokumentation är lika viktig som koden den beskriver. I Sverige, där många team arbetar med internationella partners men kommunicerar internt på svenska, finns det specifika utmaningar kring hur man dokumenterar sina API:er. Den här lektionen går igenom vanliga verktyg, standarder och bästa praxis som används i svenska mjukvaruteam.

Vad är ett API och varför behöver det dokumenteras?

Ett API (Application Programming Interface) är ett gränssnitt som låter olika system prata med varandra. Det kan vara ett REST-API, ett GraphQL-API eller ett äldre SOAP-baserat API. Oavsett typ behöver varje API en dokumentation som förklarar vad det gör, hur man anropar det och vad man kan förvänta sig tillbaka.

Utan dokumentation är ett API svåranvänt – det är som att köpa en maskin utan instruktionsbok. Bra dokumentation sparar tid för alla som ska integrera mot systemet, oavsett om det är externa partners eller det egna backend-teamet.

OpenAPI-standarden

Den vanligaste standarden för att dokumentera REST-API:er idag är OpenAPI (tidigare känd som Swagger). Med OpenAPI beskriver man sina endpoints, parametrar, request- och response-format i en YAML- eller JSON-fil. Många svenska team genererar denna spec automatiskt från koden, till exempel med hjälp av bibliotek som springdoc i Java eller fastapi:s inbyggda stöd i Python.

Fördelen med OpenAPI är att den är maskinläsbar. Det innebär att verktyg som Swagger UI automatiskt kan generera en interaktiv dokumentationssida där man kan prova endpoints direkt i webbläsaren.

Vanliga verktyg i svenska team

Förutom Swagger UI används Postman flitigt i svenska team – både för att testa API-anrop och för att dela dokumentation med kollegor. Postman har funktioner för att skapa samlingar av requests, lägga till beskrivningar och exportera dokumentation som kan delas med externa intressenter.

Redoc är ett annat populärt alternativ som genererar snygga, statiska dokumentationssidor från en OpenAPI-spec. Det lämpar sig väl när man vill publicera dokumentation till externa partners eller kunder.

Vad ska en bra API-dokumentation innehålla?

En professionell API-dokumentation bör innehålla en tydlig beskrivning av varje endpoint – vad den gör, vilka parametrar den tar emot och vilka HTTP-statuskoder den kan returnera. Man bör också inkludera konkreta kodexempel, helst på flera programmeringsspråk, som visar hur man gör ett riktigt anrop.

Autentisering är en annan viktig del att dokumentera. Använder API:et API-nycklar, OAuth 2.0 eller JWT-tokens? Detta behöver förklaras tydligt, annars fastnar alla integratörer på exakt det steget.

Svenska team följer ofta principen att dokumentation ska skrivas på engelska om API:et är externt, men kan använda svenska i intern dokumentation och kommentarer. Det är en pragmatisk avvägning som speglar arbetsmarknaden och de flesta ramverks engelska terminologi.

Versionering av API:er

När ett API förändras är det viktigt att hantera det på ett kontrollerat sätt. Många team använder versionering i URL:en, till exempel /api/v1/users och /api/v2/users. Det ger konsumenterna av API:et tid att anpassa sig till förändringar utan att deras integration går sönder direkt.

Det är god praxis att dokumentera vad som har förändrats mellan versioner i en changelog. Det visar respekt för de som använder ditt API och minskar risken för frustration och onödig felsökning.

Automatiserad dokumentation och continuous delivery

De bästa svenska teamen ser dokumentation som en del av leveransen, inte ett efterarbete. Det innebär att API-dokumentationen uppdateras automatiskt när koden ändras, och att den ingår i CI/CD-pipelinen. På så vis är dokumentationen alltid aktuell och synkroniserad med den faktiska implementationen.