Kurs NestJS · Moduł 11: Swagger i OpenAPI

Wersjonowanie API - ery Imperium

5 min czytania ·
W tej lekcji6

Zmiana w API, z którego korzysta kilku klientów, ma jedną nieprzyjemną właściwość: nie da się jej wycofać z cudzych aplikacji. Usuwasz pole, którego nikt - jak sądzisz - nie używa, i tego samego popołudnia dowiadujesz się, że używał go integrator z drugiego końca kraju.

Rzym radził sobie z tym przez ery. Prawo Republiki nie znikało wraz z nastaniem Cesarstwa - obowiązywało dalej dla spraw wszczętych wcześniej, a nowe reguły szły obok. Wersjonowanie API jest tym samym: stara wersja żyje, dopóki ktoś z niej korzysta, a zmiany trafiają do nowej.

Trzy strategie

NestJS zna trzy sposoby wskazania wersji:

  • URI Versioning - wersja w ścieżce adresu, jak /v1/legiones. Najczęściej używana, bo widać ją w logach, w przeglądarce i w zakładkach.
  • Header Versioning - wersja w nagłówku HTTP, na przykład X-Version: 1. Adres pozostaje czysty, ale wersji nie widać bez podglądu żądania.
  • Media Type Versioning - wersja w nagłówku Content-Type. Najbardziej zgodna z duchem HTTP i najrzadziej spotykana w praktyce.

Przy URI Versioning z wersją pierwszą adres wygląda tak: /v1/legiones. Nie /legiones?version=1 - to byłby parametr zapytania, nie wersja. Nie /legiones/v1 - tu v1 wyglądałoby jak identyfikator zasobu. I nie /legiones z nagłówkiem X-Version - to już inna strategia.

Włączenie wersjonowania

Wersjonowanie włącza się raz, w main.ts:

async function bootstrap() {
  const app = await NestFactory.create(AppModule);

  app.enableVersioning({
    type: VersioningType.URI,
    defaultVersion: '1',
  });

  await app.listen(3000);
}

Zapis składa się z czterech części w stałej kolejności: app.enableVersioning({ otwiera konfigurację, type: VersioningType.URI, wybiera strategię, defaultVersion: '1' ustala wersję dla kontrolerów, które jej nie podają, a }); domyka.

defaultVersion warto ustawić od razu. Bez niego każdy kontroler bez jawnej wersji przestanie odpowiadać - a przy włączaniu wersjonowania w istniejącym projekcie to zwykle wszystkie kontrolery naraz.

Kontroler w wersji

Kontroler deklaruje swoją wersję w tym samym dekoratorze, w którym podaje ścieżkę:

@Controller({
  path: 'legiones', version: '1' })
export class LegionV1Controller {}

Kolejność zapisu jest stała: @Controller({ otwiera obiekt konfiguracji, path: 'legiones', version: '1' }) podaje ścieżkę i wersję, a export class LegionV1Controller {} deklaruje samą klasę.

Zwróć uwagę, że @Controller('legiones') z napisem zamienia się tu w @Controller({ path, version }) z obiektem - to ta sama funkcja, tylko w wariancie przyjmującym więcej opcji. Pojedyncze metody można wersjonować osobno dekoratorem @Version('2'), gdy tylko jedna z nich się zmieniła.

Nazwa klasy - LegionV1Controller - nie ma znaczenia dla routingu; wersję ustala wyłącznie pole version. Warto ją jednak nazwać zgodnie z wersją, bo w projekcie z dwiema erami dwie klasy LegionController w różnych plikach szybko stają się źródłem pomyłek.

Osobna dokumentacja dla każdej wersji

Jeden dokument Swagger z pomieszanymi wersjami jest mniej użyteczny niż dwa osobne. Proces ma cztery kroki, w tej kolejności:

  1. app.enableVersioning() - najpierw aplikacja musi w ogóle rozróżniać wersje.
  2. DocumentBuilder dla każdej wersji - osobna konfiguracja z własnym tytułem i numerem.
  3. SwaggerModule.createDocument z opcją include - zbudowanie dokumentu wyłącznie z wybranych modułów.
  4. SwaggerModule.setup dla każdej wersji - wystawienie każdego dokumentu pod własnym adresem.
const configV1 = new DocumentBuilder()
  .setTitle('Legion API v1')
  .setDescription('Pierwsza era Imperium')
  .setVersion('1.0')
  .setContact('Kancelaria', 'https://imperium.rome', 'kancelaria@imperium.rome')
  .setLicense('MIT', 'https://opensource.org/licenses/MIT')
  .addServer('https://api.imperium.rome')
  .addTag('Legiony')
  .addBearerAuth(undefined, 'JWT-auth')
  .build();

const documentV1 = SwaggerModule.createDocument(app, configV1, {
  include: [LegionV1Module],
});

SwaggerModule.setup('api/v1', app, documentV1);

DocumentBuilder buduje się łańcuchem metod, z których każda dokłada jeden element opisu: setTitle, setDescription i setVersion to podstawa, setContact wskazuje, do kogo pisać, setLicense podaje licencję, addServer - adres, pod którym API naprawdę działa, addTag deklaruje grupę endpointów, a addBearerAuth włącza pole na token.

Opcja include uwzględnia w dokumentacji tylko wybrane moduły. Nie dodaje plików CSS do Swagger UI, nie importuje zewnętrznych specyfikacji OpenAPI i nie włącza dodatkowych dekoratorów. To ona sprawia, że dokument v1 zawiera wyłącznie endpointy pierwszej ery - bez niej oba dokumenty byłyby identyczne i pokazywałyby całe API.

Na końcu SwaggerModule.setup('api/v1', ...) wystawia dokument pod adresem /api/v1. Drugą wersję budujesz analogicznie: configV2 z własnym tytułem i numerem, include: [LegionV2Module], a na końcu setup('api/v2', ...).

Wycofywanie endpointów

Wersja druga nie unieważnia pierwszej z dnia na dzień. Endpointy, które mają zniknąć, oznacza się najpierw jako wycofane:

@ApiOperation({
  summary: 'Lista legionów (stara wersja)',
  deprecated: true,
})
@Get()
findAllLegacy() {
  return this.legionService.findAll();
}

Endpoint oznaczasz jako wycofany właściwością deprecated: true w @ApiOperation. Nie removed, nie obsolete, nie disabled - te trzy nazwy brzmią sensownie, ale w OpenAPI nie istnieją; specyfikacja zna wyłącznie deprecated.

W Swagger UI taki endpoint zostaje przekreślony i opatrzony ostrzeżeniem, ale nadal działa. I o to chodzi: oznaczenie jest zapowiedzią, nie wyłączeniem. Daje integratorom czas na przejście, zanim endpoint zniknie naprawdę - a bez tego okresu przejściowego wersjonowanie nie ma sensu, bo zmiana i tak łamie cudze aplikacje.

Podsumowanie

Prawo Republiki obowiązuje, dopóki są sprawy wszczęte za Republiki:

  • trzy strategie: URI (wersja w ścieżce), Header (w nagłówku, np. X-Version), Media Type (w Content-Type),
  • przy URI Versioning adres wygląda tak: /v1/legiones - nie /legiones?version=1, nie /legiones/v1,
  • włączenie w main.ts: app.enableVersioning({ → type: VersioningType.URI, → defaultVersion: '1' → });,
  • defaultVersion chroni kontrolery, które wersji nie podają,
  • kontroler wersjonowany: @Controller({ → path: 'legiones', version: '1' }) → export class LegionV1Controller {},
  • osobna dokumentacja w czterech krokach: app.enableVersioning() → DocumentBuilder dla każdej wersji → createDocument z include → SwaggerModule.setup dla każdej wersji,
  • DocumentBuilder: setTitle, setDescription, setVersion, setContact, setLicense, addServer, addTag, addBearerAuth,
  • opcja include uwzględnia tylko wybrane moduły - nie dodaje CSS, nie importuje zewnętrznych specyfikacji, nie włącza dekoratorów,
  • deprecated: true w @ApiOperation oznacza endpoint jako wycofany - nie removed, nie obsolete, nie disabled; endpoint nadal działa.

W następnej lekcji zbierzemy cały moduł w jeden projekt - kompletną dokumentację Imperium API. A na razie zapamiętaj: wersjonowanie nie służy do wprowadzania zmian. Służy do tego, żeby zmiana nie zepsuła nikomu dnia.

Kod do tej lekcji: src/versioning.ts
// Wersjonowanie API z dokumentacja Swagger
import { VersioningType } from '@nestjs/common';
import { DocumentBuilder, SwaggerModule } from '@nestjs/swagger';

// Konfiguracja wersjonowania w main.ts
async function bootstrap() {
  // const app = await NestFactory.create(AppModule);

  // TODO: Wlacz URI versioning z defaultVersion '1'
  // app.enableVersioning({
  //   type: VersioningType.URI,
  //   defaultVersion: '1',
  // });

  // TODO: Stworz DocumentBuilder dla wersji 1
  const configV1 = new DocumentBuilder()
    .setTitle('Imperium API v1')
    .setDescription('Era Republiki')
    .setVersion('1.0')
    .build();

  // TODO: Stworz DocumentBuilder dla wersji 2
  // const configV2 = new DocumentBuilder()
  //   .setTitle('Imperium API v2')
  //   .setDescription('Era Cesarstwa')
  //   .setVersion('2.0')
  //   .build();

  // TODO: Stworz osobne dokumenty Swagger dla kazdej wersji
  // const docV1 = SwaggerModule.createDocument(app, configV1);
  // SwaggerModule.setup('api/v1/docs', app, docV1);

  // const docV2 = SwaggerModule.createDocument(app, configV2);
  // SwaggerModule.setup('api/v2/docs', app, docV2);

  console.log("Swagger v1: http://localhost:3000/api/v1/docs");
  console.log("Swagger v2: http://localhost:3000/api/v2/docs");
}

bootstrap();

console.log("=== Strategie wersjonowania ===");
console.log("URI: /v1/legiones, /v2/legiones");
console.log("Header: X-API-Version: 1");
console.log("Media Type: Accept: application/json;v=1");
console.log("");
console.log("Kazda wersja moze miec osobny dokument Swagger");
console.log("deprecated: true oznacza wycofany endpoint");

Hasła z dokumentacji w tej lekcji

Widzisz błąd w tej lekcji?

Sprawdź się

Odpowiedz na pytania z tej lekcji. Wybierz odpowiedź, a od razu zobaczysz, czy jest poprawna.

  1. 1. Jak wygląda URL endpointu przy URI Versioning z wersją 1?

  2. 2. Jak oznaczyć endpoint jako wycofany (deprecated) w @ApiOperation?

To 2 z 3 pytań do tej lekcji. Pozostałe rozwiążesz w grze.

Zadania praktyczne w grze

  • Układanie w pionie

    Uporządkuj kroki tworzenia wersjonowanego API z osobnymi dokumentami Swagger:

  • Edytor kodu

    Stwórz DocumentBuilder dla wersji 1 i wersji 2 API z odpowiednimi ustawieniami

  • Układanie w pionie

    Ułóż elementy deklaracji wersjonowanego kontrolera w prawidłowej kolejności:

  • Klikanie w kolejności

    Ułóż elementy włączania URI Versioning w main.ts:

  • Edytor kodu

    Stwórz konfigurację z title, description, version, contact, license, servers, tags i bearerAuth

  1. PytanieURI Versioning w NestJS
  2. Ułóż w kolejnościTworzenie wersjonowanego API z Swagger
  3. Zadanie z kodemWersjonowane dokumenty Swagger
  4. PytanieDeprecated endpoint w Swagger
  5. Ułóż w kolejnościWersjonowany kontroler NestJS
  6. Kliknij w kolejnościWłączanie wersjonowania URI
  7. PytanieOpcja include w createDocument
  8. Zadanie z kodemKompletna konfiguracja DocumentBuilder

Przydatne artykuły