Swagger, etkileşimli ve kullanıcı dostu API belgeleri oluşturmaya yönelik ücretsiz, açık kaynaklı bir çerçevedir. Bir API'yi çeşitli girdilerle test etmenize olanak tanıyan etkileşimli web sayfaları oluşturur.

Swagger, hem JSON hem de XML yüklerini destekler. Oluşturduğu belgeler, geliştiricilerin ve geliştirici olmayanların kullanması için uygundur.

NestJS web API'lerinizi, IDE'nizden ayrılmak zorunda kalmadan basit dekoratörler kullanarak Swagger aracılığıyla belgeleyebilirsiniz.

1. Adım: API Oluşturma

Başlamadan önce, Swagger'ın belgelerini oluşturacağı bir demo API oluşturmalısınız.

NestJS CLI'yi kullanarak demo API'yi sıfırdan oluşturacaksınız.

İlk olarak, aşağıdakileri çalıştırarak yeni bir NestJS projesi oluşturun:

yuva yeni <projenizin adı>

Ardından, dizini çalıştırarak önceden oluşturulmuş projenize değiştirin:

CD <projenizin adı>

Ardından, aşağıdakileri çalıştırarak CLI ile bir REST API oluşturacaksınız:

yuva oluşturma kaynak demosu --özellik yok

“Hangi taşıma katmanını kullanıyorsunuz?” diye soran bir sorgu göreceksiniz. seçme REST API'si.

instagram viewer

"CRUD giriş noktaları oluşturmak ister misiniz?" diye soran başka bir sorgu göreceksiniz. Tip Y ve vur Girmek.

Yukarıdaki komut üretir tamamen işlevsel bir REST API CRUD uç noktaları ile ve birim test dosyaları olmadan. Bu nedenle, --özellik yok yukarıdaki komutta bayrak.

2. Adım: Swagger'ı yükleyin

Swagger'ı ve Express UI kitaplığını aşağıdakileri çalıştırarak yükleyin:

npm Yüklemek--save @nestjs/swagger swagger-ui-express

3. Adım: Swagger'ı Yapılandırın

senin içinde ana.ts dosya, içe aktarma SwaggerModule ve Belge Oluşturucu itibaren @nestjs/swagger.

DocumentBuilder, temel bir belgenin yapılandırılmasına yardımcı olur. Birlikte zincirleyebileceğiniz ve kapatabileceğiniz birkaç yöntem sunar. inşa etmek yöntem.

Bu yöntemler, başlık, açıklama ve sürüm gibi birçok özelliğin yapılandırılmasını sağlar.

Oluşturmak yapılandırma nesne değişkeni önyükleme şöyle işlev görür:

const yapılandırma = yeni Belge Oluşturucu()
 .setTitle('Demo API')
 .setDescription('Bir Demo API'si ile birlikte CRUD işlevselliği')
 .setVersion('1.0')
 .inşa etmek();

DocumentBuilder'ın yeni bir örneği, aşağıdakilerle eşleşen bir temel belge oluşturur. OpenAPI Spesifikasyonu. Daha sonra bu örneği uygun yöntemlerle başlığı, açıklamayı ve sürümü ayarlamak için kullanabilirsiniz.

Ardından, temel belge kullanılarak tanımlanan tüm HTTP yolları ile eksiksiz bir belge oluşturmanız gerekecektir.

Bunu yapmak için, oluşturmakBelge SwaggerModule'deki yöntem. createDocument iki bağımsız değişkeni kabul eder: bir uygulama örneği ve bir Swagger seçenekleri nesnesi. Bu çağrının sonucunu daha sonra kullanmak üzere bir değişkende saklayın:

constbelge = SwaggerModule.createDocument (uygulama, yapılandırma);

Ardından, arayın kurmak SwaggerModule'deki yöntem. Kurulum yöntemi üç argüman alır:

  1. Swagger UI yolu. Geleneksel olarak, “api” kullanabilirsiniz.
  2. Bir uygulama örneği
  3. tam belge

Ayrıca, kurulum yöntemi isteğe bağlı bir seçenekler nesnesi alır. Görmek NestJS'nin Swagger belge seçenekleriyle ilgili belgeleri hakkında daha fazla bilgi edinmek için.

Şöyle:

SwaggerModule.setup('API', uygulama, belge);

Başvurunuzu başlatın ve şuraya gidin: http://localhost:/api

Sayfada görüntülenen Swagger kullanıcı arayüzünü görmelisiniz.

Yukarıdaki resim, kontrol cihazınızdaki tüm HTTP yollarının tanımlı olduğu Swagger UI'nin varsayılan görünümüdür. API işlevselliğinize uyacak şekilde özelleştirmeniz gerekir.

4. Adım: API Özelliklerini Özelleştirin

Varsayılan olarak Swagger, tüm HTTP rota bölümünün önüne "varsayılan" yazan bir başlık ekler. Bunu, denetleyici sınıfınıza açıklama ekleyerek değiştirebilirsiniz. @ApiEtiketler dekoratör ve tercih ettiğiniz etiketi argüman olarak iletin.

Şöyle:

// demo.denetleyici.ts
içe aktarmak { API Etiketleri } itibaren '@nestjs/swagger';
@ApiEtiketler('Demo')
@Kontrolör('demo')
ihracatsınıf DemoDenetleyici {

Şemalar bölümü, API'nizdeki Veri aktarımı nesnelerini içerir. Şu anda, kullanıcı arayüzü bunların hiçbir özelliğini içermiyor.

Kullanıcı arabiriminde özelliklerini bildirmek için dekoratörler eklemeniz yeterlidir. Gerekli her özelliği @ApiProperty dekoratör. ile isteğe bağlı özelliklere açıklama ekleyin @ApiPropertyOpsiyonel dekoratör.

Örneğin:

// create-demo.dto.ts
içe aktarmak { ApiProperty, ApiPropertyOptional } itibaren '@nestjs/swagger';
ihracatsınıf CreateDemoDto {
@ApiProperty({
tip: Sicim,
 açıklama: 'Bu gerekli bir özelliktir',
 })
 Emlak: sicim;
@ApiPropertyOpsiyonel({
tip: Sicim,
 açıklama: 'Bu isteğe bağlı bir özelliktir',
 })
 isteğe bağlıÖzellik: sicim;
}

@ApiProperty ve @ApiPropertyOptional dekoratörlerinin her biri bir options nesnesini kabul eder. Bu nesne, aşağıdaki özelliği açıklar.

options nesnesinin TypeScript değil JavaScript kullandığını unutmayın. Bu nedenle JavaScript türü bildirimleri (yani String, string değil).

Veri aktarımı nesnesinin özelliklerine açıklama eklemek, Şemalar bölümüne beklenen verilere bir örnek ekler. Ayrıca, beklenen verilerin bir örneğiyle ilişkili HTTP yolunu da günceller.

Adım 5: API Yanıtlarını Ayarlayın

Denetleyici sınıfınızda, @ApiResponse dekoratörler, her HTTP rotası için tüm olası yanıtları belgeleyecek. Her uç nokta için farklı @ApiResponse dekoratörleri, beklenecek yanıtların türünü tanımlar.

açıkladık ortak HTTP yanıtları, ne anlama geldiklerini bilmiyorsanız.

@ApiResponse dekoratörleri, yanıtı tanımlayan isteğe bağlı bir nesneyi kabul eder.

Ortak POST Yanıtları

Bir POST isteği için olası yanıtlar şunları içerir:

  • ApiCreatedResponse, başarılı 201 oluşturulan yanıtlar için.
  • ApiUnprocessableEnityResponse, başarısız 422 işlenmeyen varlık yanıtı için.
  • ApiForbiddenYanıt, 403 yasak yanıt için.

Örneğin:

// demo.denetleyici.ts
@Postalamak()
@ApiCreatedResponse({ açıklama: 'Başarıyla Oluşturuldu' })
@ApiUnprocessableEntityResponse({ açıklama: 'Kötü İstek' })
@ApiForbiddenYanıt({ açıklama: 'Yetkisiz İstek' })
 oluşturmak(@Gövde() createDemoDto: CreateDemoDto) {
dönüşBu.demoService.create (createDemoDto);
 }

Ortak GET Yanıtları

GET istekleri için olası yanıtlar şunları içerir:

  • ApiOkResponse, 200 tamam yanıt için.
  • ApiForbiddenYanıt, 403 yasak yanıt için.
  • ApiNotFoundResponse, 404 bulunamadı yanıt için.

Örneğin:

// demo.denetleyici.ts
@Almak()
@ApiOkResponse({ açıklama: 'Kaynaklar başarıyla döndürüldü' })
@ApiForbiddenYanıt({ açıklama: 'Yetkisiz İstek' })
 hepsini bul() {
dönüşBu.demoService.findAll();
 }
@Almak(':İD')
@ApiOkResponse({ açıklama: 'Kaynak başarıyla döndürüldü' })
@ApiForbiddenYanıt({ açıklama: 'Yetkisiz İstek' })
@ApiNotFoundResponse({ açıklama: 'Kaynak bulunamadı' })
 birini bul(@Param('yaptım: sicim) {
dönüşBu.demoService.findOne(+id);
 }

Ortak YAMA ve GÜNCELLEME Yanıtları

YAMA ve GÜNCELLEME istekleri için olası yanıtlar şunları içerir:

  • ApiOkResponse, 200 tamam yanıt için.
  • ApiNotFoundResponse, 404 bulunamadı yanıt için.
  • Apiİşlenmeyen Varlık Yanıtı, başarısız 422 işlenmeyen varlık yanıtı için.
  • ApiForbiddenYanıt, 403 yasak yanıt için.

Örneğin:

// demo.denetleyici.ts
@Yama(':İD')
@ApiOkResponse({ açıklama: 'Kaynak başarıyla güncellendi' })
@ApiNotFoundResponse({ açıklama: 'Kaynak bulunamadı' })
@ApiForbiddenYanıt({ açıklama: 'Yetkisiz İstek' })
@ApiUnprocessableEntityResponse({ açıklama: 'Kötü İstek' })
 Güncelleme(@Param('yaptım: sicim, @Gövde() updateDemoDto: UpdateDemoDto) {
dönüşBu.demoService.update(+id, updateDemoDto);
 }

Ortak DELETE Yanıtları

DELETE istekleri için olası yanıtlar şunları içerir:

  • ApiOkResponse, 200 tamam yanıt için.
  • ApiForbiddenYanıt, 403 yasak yanıt için.
  • ApiNotFoundResponse, 404 bulunamadı yanıt için.

Örneğin:

// demo.denetleyici.ts
@Silmek(':İD')
@ApiOkResponse({ açıklama: 'Kaynak başarıyla döndürüldü' })
@ApiForbiddenYanıt({ açıklama: 'Yetkisiz İstek' })
@ApiNotFoundResponse({ açıklama: 'Kaynak bulunamadı' })
 kaldırmak(@Param('yaptım: sicim) {
dönüşBu.demoService.remove(+id);
 }

Bu dekoratörler, belgelerinizi olası yanıtlarla doldurur. Her rotanın yanındaki açılır menüyü kullanarak bunları görüntüleyebilirsiniz.

Belgelerinizi Görüntüleme

Kurulumunuz tamamlandığında, belgelerinizi şurada görüntüleyebilirsiniz: yerel ana bilgisayar:/api. Etkileşimli API belgelerinizi getirmelidir.

Swagger API belgelerinin esasları açıklama, yanıt türleri ve şema tanımıdır. Bunlar, iyi API belgeleri oluşturmak için gereken temel şeylerdir.