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