Varför dokumentation spelar roll

API:er konsumeras av människor — utvecklare som behöver förstå vad de kan göra, hur autentisering fungerar och vad de kan förvänta sig av svaren. Tydlig dokumentation minskar supportärenden, snabbar upp integrationer och gör ditt API enklare att underhålla över tid.

På Uppsala kommuns API-plattform är OpenAPI 3.x källan till sanning. Allt — katalogvyn, "Try it"-funktionen, klientgenerering — utgår från specen. Om specen är slarvig blir portalen det också.

Skriv en bra OpenAPI-spec

Beskriv API:et som helhet

I info-blocket: ge API:et ett beskrivande namn, en kort sammanfattning och en längre description i Markdown som förklarar syftet, målgruppen och eventuella förutsättningar.

info:
  title: Föreningsregister
  version: 1.0.0
  summary: API för Uppsala kommuns föreningsregister
  description: |
    Returnerar publika föreningar registrerade i kommunens föreningsregister.

    **Målgrupp:** interna förvaltningar och bidragsadministration.

    **Datakälla:** föreningsregistret, uppdateras dagligen kl 06:00.

Beskriv varje operation

Varje endpoint ska ha summary, description, operationId och minst ett exempelsvar per statuskod du dokumenterar.

paths:
  /foreningar:
    get:
      summary: Lista föreningar
      description: |
        Returnerar en paginerad lista av aktiva föreningar.
        Använd `?type=` för att filtrera på föreningstyp.
      operationId: listForeningar
      parameters:
        - name: type
          in: query
          schema:
            type: string
            enum: [idrott, kultur, samhalle]
      responses:
        '200':
          description: Lista av föreningar
          content:
            application/json:
              examples:
                tva-foreningar:
                  summary: Två föreningar i svaret
                  value:
                    items:
                      - id: "f-001"
                        namn: "Uppsala Schackklubb"
                        typ: "kultur"
                    nextPage: null

Dokumentera fel — inte bara lyckade svar

Lista de viktigaste felkoderna (400, 401, 403, 404, 429, 5xx) och ge ett exempel per kod. Använd plattformens standardfelschema:

components:
  schemas:
    Error:
      type: object
      required: [code, message]
      properties:
        code:
          type: string
          example: VALIDATION_FAILED
        message:
          type: string
          example: Fältet "type" måste vara ett av: idrott, kultur, samhalle.
        requestId:
          type: string
          example: 7c3e8d6e-1f2a-4b8c-9e1d-0a2b3c4d5e6f

Riktlinjer för språk och ton

• Skriv på svenska i description-fält som riktar sig till interna utvecklare. Tekniska termer (HTTP-metoder, statuskoder, headers) behåller sina engelska namn.
• Var konkret. "Returnerar en lista föreningar" är bättre än "Hämtar data".
• Förklara konventioner en gång. Om alla endpoints paginerar likadant — beskriv det i info.description, inte i varje operation.
• Visa, hänvisa inte. Ett konkret exempel är värt mer än en lång prosa- förklaring.

Checklista innan du publicerar

• info.title, summary och description är ifyllda och korrekta.
• Varje operation har summary, description och operationId.
• Minst ett example per dokumenterad statuskod.
• Felkoder följer plattformens standardschema.
• Spec validerar utan varningar (t.ex. via Spectral eller swagger-cli validate).
• Linjerna nedan stämmer med din implementation — testat mot test-miljön.

När checklistan är grön är du redo att gå vidare till Publicera API:er.