OpenAPI (Swagger) – dokumentacja i wersjonowanie API w 2026

TL;DR

OpenAPI (dawniej Swagger) to standard opisu REST API w formacie YAML/JSON. Z jednej specyfikacji możesz wygenerować dokumentację (Swagger UI, Redoc), klienty w różnych językach i serwery szkieletowe. Utrzymuj spec w repozytorium obok kodu i traktuj ją jako kontrakt między frontendem a backendem. Wersjonowanie API (np. /v1/, /v2/) planuj od początku.

Dla kogo to jest

Deweloperów backendu i frontendu współpracujących przez API
Architektów API i product ownerów
Zespołów wdrażających API dla zewnętrznych klientów

Fraza (SEO)

openapi swagger, dokumentacja api, wersjonowanie api, specyfikacja rest api

Po co OpenAPI?

Jedna specyfikacja – opis endpointów, request/response, typy, przykłady
Czytelna dokumentacja – Swagger UI, Redoc – dla zespołu i partnerów
Generowanie kodu – klienty (TypeScript, Python, etc.) i szkielet serwera z jednego pliku
Testy – narzędzia (Postman, Dredd) mogą walidować API względem specyfikacji
Kontrakt – frontend i backend uzgadniają spec; zmiany = świadoma wersja

Podstawowa struktura specyfikacji

openapi: 3.0.3
info:
  title: Moje API
  version: 1.0.0
servers:
  - url: https://api.example.com/v1
paths:
  /users:
    get:
      summary: Lista użytkowników
      parameters:
        - name: page
          in: query
          schema:
            type: integer
            default: 1
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/User'
  /users/{id}:
    get:
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
components:
  schemas:
    User:
      type: object
      properties:
        id:
          type: integer
        email:
          type: string
          format: email
        name:
          type: string

Dokumentacja z specyfikacji

Swagger UI – interaktywna dokumentacja, możliwość wywołania requestów (np. z auth)
Redoc – czytelny, „książkowy” layout
Oba można wygenerować z tego samego pliku OpenAPI (np. w CI lub przy starcie serwera)

Generowanie kodu

openapi-generator (OpenAPI Generator) – klienty: TypeScript, Python, Java, Go… oraz szkielet serwera
Orval (dla TypeScript/React) – generuje typy i funkcje wywołań API z OpenAPI
Dzięki temu frontend zawsze ma aktualne typy i endpointy po odświeżeniu specyfikacji

Wersjonowanie API

URL – np. /v1/users, /v2/users – czytelne, cache’owanie i proxy proste
Header – np. Accept: application/vnd.api.v1+json – czystszy URL, mniej popularne
Data – przy wersjonowaniu przez URL ustal politykę: kiedy v1 jest deprecated, kiedy wygaszasz; komunikuj to w dokumentacji i nagłówkach (np. Deprecation, Sunset)

Rekomendacja: wersja w URL (/v1/) dla publicznego API; wewnętrznie można być elastyczniejszym.

Best practices

Spec jako źródło prawdy – trzymaj w repo, aktualizuj przy zmianach API; CI może walidować, że serwer spełnia spec (np. przez testy kontraktowe)
Semantic versioning – np. 1.0.0 → 1.1.0 przy dodaniu pola (backward compatible), 2.0.0 przy breaking change
Opisy i przykłady – description, example w schematach ułatwiają życie konsumentom API
Sekcja security – opisz wymagane nagłówki (Bearer, API key); Swagger UI pozwoli je ustawić przy testach

Checklista

Plik OpenAPI w repozytorium (YAML lub JSON)
Dokumentacja (Swagger UI / Redoc) dostępna dla zespołu i klientów
Generowanie klienta (lub typów) w buildzie
Zasady wersjonowania (v1, v2) i deprecation
Testy kontraktowe (opcjonalnie) – odpowiedzi serwera zgodne ze specyfikacją

FAQ

Czy OpenAPI zastępuje dokumentację „ręczną”?

Nie musi. OpenAPI opisuje kontrakt (endpointy, schematy). Możesz dołożyć osobną dokumentację (np. „Jak uzyskać token”, scenariusze biznesowe) w wiki lub w opisach w samej specyfikacji.

Co przy GraphQL?

OpenAPI dotyczy REST. Dla GraphQL używa się GraphQL schema i narzędzi typu GraphQL Playground, Apollo Studio. Koncepcja „jedna spec = dokumentacja + generowanie” jest podobna.

Jak utrzymać zgodność kodu ze specyfikacją?

Opcja 1: generuj szkielet z OpenAPI i rozwijaj go. Opcja 2: pisz kod ręcznie, a w CI generuj spec z kodu (np. przez adnotacje w Javie, dekoratory w Pythonie) i porównuj z „złotym” plikiem OpenAPI. Opcja 3: testy kontraktowe – request/response z testów walidowane względem specyfikacji.

Chcesz uporządkować dokumentację API lub wdrożyć OpenAPI?

Kontakt