Kurs NestJS · Moduł 11: Swagger i OpenAPI
Wersjonowanie API - ery Imperium
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:
app.enableVersioning()- najpierw aplikacja musi w ogóle rozróżniać wersje.DocumentBuilderdla każdej wersji - osobna konfiguracja z własnym tytułem i numerem.SwaggerModule.createDocumentz opcjąinclude- zbudowanie dokumentu wyłącznie z wybranych modułów.SwaggerModule.setupdla 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 (wContent-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'→});, defaultVersionchroni kontrolery, które wersji nie podają,- kontroler wersjonowany:
@Controller({→path: 'legiones', version: '1' })→export class LegionV1Controller {}, - osobna dokumentacja w czterech krokach:
app.enableVersioning()→DocumentBuilderdla każdej wersji →createDocumentzinclude→SwaggerModule.setupdla każdej wersji, DocumentBuilder:setTitle,setDescription,setVersion,setContact,setLicense,addServer,addTag,addBearerAuth,- opcja
includeuwzględnia tylko wybrane moduły - nie dodaje CSS, nie importuje zewnętrznych specyfikacji, nie włącza dekoratorów, deprecated: truew@ApiOperationoznacza endpoint jako wycofany - nieremoved, nieobsolete, niedisabled; 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. Jak wygląda URL endpointu przy URI Versioning z wersją 1?
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
Zadania po tej lekcji
- PytanieURI Versioning w NestJS
- Ułóż w kolejnościTworzenie wersjonowanego API z Swagger
- Zadanie z kodemWersjonowane dokumenty Swagger
- PytanieDeprecated endpoint w Swagger
- Ułóż w kolejnościWersjonowany kontroler NestJS
- Kliknij w kolejnościWłączanie wersjonowania URI
- PytanieOpcja include w createDocument
- Zadanie z kodemKompletna konfiguracja DocumentBuilder