Rio Document Generator

Retter.io projeleri için Swagger/OpenAPI dökümantasyonu oluşturucu.

ÖNEMLİ: Bu döküman oluşturucu yalnızca Retter.io altyapısı kullanan projeler için tasarlanmıştır ve bu altyapı ile çalışır.

Kurulum

npm install rio-document-generator
# veya
pnpm add rio-document-generator

Kullanım

1. Konfigürasyon Dosyası Oluşturma

Proje dizininizde swagger-generator.config.js dosyası oluşturun:

module.exports = {
  environments: {
    test: {
      baseUrl: 'https://api.test.example.com',
      projectId: 'test-project',
      description: 'Test Environment',
    },
    prod: {
      baseUrl: 'https://api.example.com',
      projectId: 'prod-project',
      description: 'Production Environment',
    }
  },
  apidog: {
    enabled: false,
    url: 'https://api.apidog.com/v1/projects/{projectId}/import-openapi',
  }
};

2. Package.json'a Script Ekleme

{
  "scripts": {
    "swagger": "rio-document-generator"
  }
}

3. Swagger Oluşturma

Aşağıdaki komut seçeneklerinden birini kullanarak Swagger dökümantasyonunu oluşturabilirsiniz:

# Temel kullanım (yukarıdaki config dosyası ile)
npm run swagger

# Özel config dosyası ile kullanım
npm run swagger -- --config ./custom.config.js

# Apidog entegrasyonu ile kullanım
npm run swagger -- --apidog-api-key YOUR_API_KEY --apidog-project-id YOUR_PROJECT_ID

Komut Seçenekleri

Seçenek	Açıklama
-c, --config <path>	Özel config dosyası yolu
--apidog-api-key <key>	Apidog API anahtarı
--apidog-project-id <id>	Apidog proje ID
-h, --help	Yardım bilgisini gösterir
-v, --version	Versiyon bilgisini gösterir

Konfigürasyon Dosyası Yapısı

Alan	Tip	Açıklama	Zorunlu
environments	object	Ortam konfigürasyonları	Evet
environments.*.baseUrl	string	API base URL	Evet
environments.*.projectId	string	Proje ID	Evet
environments.*.description	string	Ortam açıklaması	Hayır
apidog	object	Apidog entegrasyon ayarları	Hayır
apidog.enabled	boolean	Apidog entegrasyonu aktif/pasif	Hayır
apidog.url	string	Apidog API URL	Hayır

Method Template ve Model Yapısı

Documentation Tag Gerekliliği

Rio projelerinde Swagger/OpenAPI dökümantasyonu oluşturabilmek için export edilecek tüm methodlara documentation tag'inin eklenmesi zorunludur. Bu tag içerisindeki bilgiler dokümantasyonda aşağıdaki şekilde kullanılır:

• consumer: API endpoint'in hangi client tarafından kullanılacağını belirtir
• method: HTTP method tipini belirtir
• description: Endpoint açıklamasını belirtir
• authentication: Kimlik doğrulama yöntemini belirtir
• instanceId: Instance ID tipini belirtir
• title: Endpoint'in OpenAPI dokümantasyonunda görünecek başlığını belirtir

Otomatik Hata Yanıtları

Sistem, kod içerisinde throw edilen CustomError'ları otomatik olarak tespit eder ve bunları OpenAPI dokümantasyonuna ekler. Örneğin:

throw new CustomError({ error: Errors.User[1000] })

Bu tür hata fırlatmaları tespit edildiğinde:

• İlgili hata dosyası otomatik olarak bulunur
• Hata içeriği ve yapısı analiz edilir
• OpenAPI dokümantasyonuna error response olarak eklenir

Model Şema Oluşturma

Swagger şemaları iki farklı yöntemle otomatik olarak oluşturulur:

1. Template Model Tanımları: Template'de belirtilen model tanımları kullanılır:

   • inputModel
   • outputModel
   • queryStringModel

2. Kod İçi Tip Tanımları: Template'de model belirtilmemişse, method tanımındaki tip bilgileri kullanılır. Örnek:

export async function validate(
  data: ClassData<ValidateUserOrderInput, ValidateUserOrderOutput | ErrorResponseBody>
): Promise<Data> {
  // ... method implementation
}

Bu örnekte:

• ValidateUserOrderInput: Input şeması olarak kullanılır
• ValidateUserOrderOutput: Output şeması olarak kullanılır

Sistem otomatik olarak bu tipleri import edilen kaynaklardan bulur ve Zod modellerini Swagger şemalarına dönüştürür.

Şema Oluşturma Önceliği

1. Önce template'deki model tanımları kontrol edilir
2. Template'de model tanımı yoksa, method imzasındaki tip tanımları kullanılır
3. İlgili modeller bulunduğunda Zod şemaları otomatik olarak Swagger şemalarına dönüştürülür

Örnek Kullanım

# Template tanımı ile
- method: updateOrder
  type: QUEUED_WRITE
  handler: order.update
  inputModel: UpdateOrderInput
  outputModel: UpdateOrderOutput
  documentation:
    - consumer: backoffice
    - method: PUT
    - authentication: token
    - instanceId: default
    - title: Sipariş Güncelleme
    - description: Mevcut bir siparişi günceller

# Kod içi tip tanımı ile
- method: validateOrder
  type: STATIC
  handler: order.validate
  # Model tanımı yok, kod içindeki tipler kullanılacak
  documentation:
    - consumer: backoffice
    - method: POST
    - authentication: token
    - instanceId: default

// Kod içi tip tanımı örneği
export async function validate(
  data: ClassData<ValidateOrderInput, ValidateOrderOutput>
): Promise<Data> {
  // Bu tiplerin Zod modelleri otomatik olarak bulunup
  // Swagger şemalarına dönüştürülecek
}

Lisans

MIT