Blog

Redocly Eğitimi: Redocly CLI Nasıl Kullanılır

Mark Ponomarev

Mark Ponomarev

9 June 2025

Redocly Eğitimi: Redocly CLI Nasıl Kullanılır

Redocly CLI hakkındaki bu kapsamlı eğitime hoş geldiniz! Redocly CLI, OpenAPI ve Swagger tanımları için güçlü, hepsi bir arada bir komut satırı aracıdır. API tanımlarınızı tüm API yaşam döngüsü boyunca oluşturmanıza, yönetmenize ve kalite kontrolü yapmanıza yardımcı olur. İster bir geliştirici, ister teknik yazar, ister API ürün yöneticisi olun, bu araç size göre bir şeyler sunar.

Bu eğitim, Redocly CLI'ya derinlemesine bir dalış yapmayı ve sizi bir başlangıç seviyesinden kendine güvenen bir kullanıcıya dönüştürmeyi amaçlamaktadır. Kurulumdan özel lint kuralları ve CI/CD entegrasyonu gibi gelişmiş özelliklere kadar her şeyi ele alacağız. Bu eğitimin sonunda, API kalitenizi ve dokümantasyonunuzu iyileştirmek için Redocly CLI'yı günlük iş akışınıza entegre edebileceksiniz.

💡
Oluşturan harika bir API Test aracı mı istiyorsunuz güzel API Dokümantasyonu?

Geliştirici Ekibinizin birlikte çalışması için entegre, Hepsi Bir Arada bir platform mu istiyorsunuz maksimum üretkenlik?

Apidog tüm taleplerinizi karşılar ve Postman'ı çok daha uygun bir fiyata değiştirir!
button

Redocly CLI Nedir?

Resmi dokümantasyonunda belirtildiği gibi, Redocly CLI sizin "hepsi bir arada OpenAPI yardımcı aracınızdır". OpenAPI 3.1, 3.0, 2.0 (eski Swagger), AsyncAPI ve daha fazlasını destekler. Size şu konularda yardımcı olmak için tasarlanmıştır:

Bu araç, hızlı yürütme ve insan tarafından okunabilir hata mesajları sağlayarak performans ve kullanıcı deneyimi göz önünde bulundurularak oluşturulmuştur.

Neden Redocly CLI Kullanmalısınız?

Günümüzün API-öncelikli dünyasında, yüksek kaliteli API tanımlarını sürdürmek çok önemlidir. Redocly CLI, bunu başarmanıza yardımcı olur:

Bu Eğitim Neleri Kapsayacak?

Bu eğitim, Redocly CLI'da ustalaşmak için adım adım bir kılavuz sağlamak üzere yapılandırılmıştır. İşte ele alacağımız konular:

Hadi başlayalım!

Bölüm 1: Redocly CLI ile Başlarken

Bu bölüm, kurulumdan ilk komutunuzu çalıştırmaya kadar Redocly CLI'yı kullanmanın ilk adımlarında size rehberlik edecektir.

Önkoşullar

Başlamadan önce, sisteminizde aşağıdakilerin kurulu olduğundan emin olun:

Kurulum

Redocly CLI'yı kurmak ve kullanmak için birkaç seçeneğiniz vardır. İhtiyaçlarınıza en uygun olanı seçin.

npx Kullanma (Hızlı kullanım için önerilir)

Redocly CLI'yı genel bir kurulum yapmadan sadece denemek istiyorsanız, npm paket çalıştırıcısı olan npx'i kullanabilirsiniz. Bu komut, Redocly CLI'nın en son sürümünü indirecek ve çalıştıracaktır.

npx @redocly/cli@latest --version

Herhangi bir redocly komutunu kullanmak için, sadece npx @redocly/cli@latest önekini ekleyin. Örneğin:

npx @redocly/cli@latest lint openapi.yaml

Bu, Redocly CLI'yı CI/CD ortamlarında kullanmanın veya sisteminizi genel paketlerle doldurmak istemiyorsanız harika bir yoludur.

npm ile Genel Kurulum

Düzenli kullanım için, genel bir kurulum daha uygundur. redocly komutunu doğrudan terminalinizde kullanılabilir hale getirir.

npm install -g @redocly/cli@latest

Kurulumdan sonra, sürümü kontrol ederek doğrulayabilirsiniz:

redocly --version

Şimdi aşağıdaki gibi komutları çalıştırabilirsiniz:

redocly lint openapi.yaml

Docker Kullanma

Docker kullanmayı tercih ediyorsanız, Redocly önceden oluşturulmuş bir Docker imajı sağlar. Bu, aracı yerel ortamınızdan izole etmek için kullanışlıdır.

Önce, imajı Docker Hub'dan çekin:

docker pull redocly/cli

Bir komut çalıştırmak için, mevcut çalışma dizininizi (API dosyalarınızın bulunduğu yer) Docker konteynerine bir birim olarak bağlamanız gerekir.

docker run --rm -v $PWD:/spec redocly/cli lint /spec/openapi.yaml

Bu komutta, $PWD, konteyner içindeki /spec dizinine bağlanan mevcut dizininizi ifade eder. Daha sonra dosyalarınıza /spec yolunu kullanarak başvurmanız gerekir.

Temel Komut Yapısı

Redocly CLI kullanmanın temel yapısı şöyledir:

redocly [komut] [argümanlar] [seçenekler]

Belirli bir komut için --help seçeneğini kullanarak her zaman yardım alabilirsiniz:

redocly lint --help

Artık Redocly CLI kurulu ve temel komut yapısını anladığınıza göre, güçlü özelliklerini keşfetmeye geçelim.

Bölüm 2: Temel Komutlar ve Özellikler

Bu bölüm, Redocly CLI'nın temel komutlarını kapsar. API tanımlarınızı nasıl lint edeceğinizi, yöneteceğinizi, belgeleyeceğinizi ve analiz edeceğinizi keşfedeceğiz. Bu bölümdeki örnekler için basit bir openapi.yaml dosyası kullanacağız.

Aşağıdaki içeriğe sahip openapi.yaml adında bir dosya oluşturalım:

openapi: 3.0.0
info:
  title: Simple Pet Store API
  version: 1.0.0
  description: A simple API to manage pets.
servers:
  - url: <http://localhost:8080/api>
paths:
  /pets:
    get:
      summary: List all pets
      operationId: listPets
      responses:
        '200':
          description: An array of pets.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Pet'
components:
  schemas:
    Pet:
      type: object
      properties:
        id:
          type: integer
          format: int64
        name:
          type: string
        tag:
          type: string

Bölüm 2.1: API Tanımlarınızı Lint Etme (lint)

API linting, API tanım dosyanızı tutarlılık, doğruluk ve stil açısından kontrol etme sürecidir. API tasarım yönergelerini uygulamanıza ve üretime ulaşmadan önce potansiyel sorunları yakalamanıza yardımcı olur.

Temel Kullanım

lint komutu, API tanımınızı bir dizi kurala göre kontrol etmek için kullanılır.

redocly lint openapi.yaml

Varsayılan olarak, redocly lint recommended kural setini kullanır. Eğer openapi.yaml dosyamızda sorunlar varsa, çıktı bunları detaylandıracaktır. Örnek dosyamız için çıktı şöyle olmalıdır:

validating openapi.yaml...
openapi.yaml: validated in 58ms

Woohoo! Your API description is valid. 🎉

Kuralları Yapılandırma

Redocly CLI, üç yerleşik yapılandırılabilir kural seti ile birlikte gelir:

--extends seçeneği ile bir kural seti belirtebilirsiniz:

redocly lint openapi.yaml --extends=minimal

Ayrıca redocly.yaml yapılandırma dosyasında kendi özel kural setlerinizi oluşturabilirsiniz. Bunu Bölüm 3'te ele alacağız.

Çıktı Biçimleri

lint komutu, diğer araçlarla entegrasyon için çok kullanışlı olan --format seçeneğini kullanarak çeşitli çıktı biçimlerini destekler.

stylish biçimini kullanma örneği:

redocly lint openapi.yaml --format=stylish

Sorunları Yoksayma

Bazen belirli bir sorunu yoksaymanız gerekebilir. Hataları ve uyarıları bastırmak için bir .redocly.lint-ignore.yaml dosyası oluşturabilirsiniz.

redocly lint openapi.yaml --generate-ignore-file

Bu komut bir yoksayma dosyası oluşturacaktır. lint komutunu tekrar çalıştırırsanız, bu dosyada listelenen sorunlar yoksayılacaktır. Bu size linting süreci üzerinde ayrıntılı kontrol sağlar.

Bölüm 2.2: bundle ve split ile API Tanımlarını Yönetme

API'niz büyüdükçe, tek, monolitik bir OpenAPI dosyasını yönetmek hantal hale gelir. Redocly CLI, bu konuda yardımcı olmak için iki komut sağlar: split ve bundle.

Büyük Bir OpenAPI Dosyasını Bölme (split)

split komutu, büyük bir API tanım dosyasını daha yönetilebilir, çok dosyalı bir yapıya ayırmanıza olanak tanır. Bileşenleri, yolları ve örnekleri ayrı dosya ve klasörlere çıkarır.

openapi.yaml dosyamızı bölelim:

redocly split openapi.yaml --outDir=split-api

Bu komut, aşağıdaki yapıya sahip bir split-api dizini oluşturacaktır:

split-api/
├── components/
│   └── schemas/
│       └── Pet.yaml
├── paths/
│   └── pets.yaml
└── openapi.yaml

split-api içindeki yeni openapi.yaml dosyası artık harici dosyalara bağlantı vermek için $ref kullanacaktır:

# split-api/openapi.yaml
openapi: 3.0.0
info:
  title: Simple Pet Store API
# ...
paths:
  /pets:
    $ref: ./paths/pets.yaml
components:
  schemas:
    Pet:
      $ref: ./components/schemas/Pet.yaml

Bu, API'nizin farklı bölümlerini yönetmeyi çok daha kolay hale getirir.

Birden Çok Dosyayı Bir Araya Getirme (bundle)

bundle komutu, split komutunun tersini yapar. Bir kök API tanım dosyasını alır ve tek, bağımsız bir dosya oluşturmak için tüm yerel $ref'leri çözer. Bu, çok dosyalı tanımları desteklemeyen araçlar için kullanışlıdır.

Bölünmüş API'mizi tek bir dosyada bir araya getirelim:

redocly bundle split-api/openapi.yaml --output bundled-api.yaml

bundled-api.yaml dosyası, orijinal openapi.yaml dosyamızla aynı içeriğe sahip olacaktır.

Dereferanslama

bundle komutu, tüm $ref'lerin (uzak olanlar dahil) çözümlendiği ve içerikleriyle değiştirildiği tamamen dereferanslanmış bir dosya da oluşturabilir.

redocly bundle split-api/openapi.yaml --output dereferenced-api.yaml --dereferenced

Bu kullanışlı olabilir, ancak dosyanın çok daha büyük olabileceğini ve döngüsel referansların JSON çıktısında sorunlara neden olabileceğini unutmayın.

Bölüm 2.3: API Dokümantasyonu Oluşturma (build-docs)

Redocly CLI'nın en güçlü özelliklerinden biri, açık kaynaklı Redoc motorunu kullanarak güzel, etkileşimli API referans dokümantasyonu oluşturma yeteneğidir.

Temel Kullanım

Dokümantasyon oluşturmak için build-docs komutunu kullanın:

redocly build-docs openapi.yaml

Bu, mevcut dizininizde bir redoc-static.html dosyası oluşturacaktır. Dokümantasyonunuzu görmek için tarayıcınızda açın.

-o veya --output seçeneği ile farklı bir çıktı dosyası belirtebilirsiniz:

redocly build-docs openapi.yaml -o my-api-docs.html

Çıktıyı Özelleştirme

Dokümantasyonunuzun görünümünü ve hissini --theme.openapi seçeneğini kullanarak özelleştirebilirsiniz. Bu, renkleri, yazı tiplerini değiştirmenize ve hatta arama çubuğu gibi kullanıcı arayüzünün bazı kısımlarını devre dışı bırakmanıza olanak tanır.

Örneğin, arama çubuğunu devre dışı bırakmak için:

redocly build-docs openapi.yaml --theme.openapi.disableSearch

Mevcut tüm tema seçeneklerini resmi Redocly dokümantasyonunda bulabilirsiniz.

Daha da fazla kontrol için, dokümantasyonu işlemek üzere kendi Handlebars şablonunuzu sağlayabilirsiniz. Bu, HTML çıktısının tam özelleştirilmesine olanak tanıyan gelişmiş bir özelliktir.

Bölüm 2.4: API İstatistiklerini Alma (stats)

stats komutu, API tanımınız hakkında yol, işlem, şema sayısı gibi faydalı metrikler sağlar.

İstatistikler Nasıl Alınır?

API'niz için istatistik almak için basitçe çalıştırın:

redocly stats openapi.yaml

Varsayılan çıktı stylish biçimindedir:

Document: openapi.yaml stats:

🚗 References: 1
📦 External Documents: 0
📈 Schemas: 1
👉 Parameters: 0
🔗 Links: 0
🔀 Path Items: 1
👷 Operations: 1
🔖 Tags: 0

openapi.yaml: stats processed in 22ms

Farklı Biçimler

lint komutu gibi, stats komutu da --format seçeneği ile farklı çıktı biçimlerini destekler. json ve markdown biçimleri özellikle kullanışlıdır.

redocly stats openapi.yaml --format=json

Bu, istatistikleri diğer araçlara veya panolara beslemek için harikadır.

redocly stats openapi.yaml --format=markdown

Bu, raporlar veya bir sonraki bölümde göreceğimiz gibi GitHub Actions özetlerinde kullanım için mükemmel olan bir Markdown tablosu oluşturur.

Bölüm 3: Gelişmiş Konular

Bu bölümde, Redocly CLI'nın bazı gelişmiş özelliklerine, güçlü yapılandırma dosyası ve CI/CD işlem hatları ile entegrasyon dahil olmak üzere dalış yapacağız.

Yapılandırma Dosyası (redocly.yaml)

Redocly CLI'yı tamamen komut satırından kullanabilseniz de, bir redocly.yaml yapılandırma dosyası, yapılandırmanızı tek bir yerde saklamanıza olanak tanır, bu da komutlarınızı daha kısa ve yapılandırmanızı yeniden kullanılabilir hale getirir.

Projemizin kök dizininde bir redocly.yaml dosyası oluşturalım:

# redocly.yaml

# This is a sample configuration file.
# For a full list of options, see the Redocly documentation.

apis:
  main:
    root: openapi.yaml

lint:
  extends:
    - recommended
  rules:
    # You can customize rules here.
    # For example, make sure all operations have a summary.
    operation-summary: error

Yapılandırma Dosyasının Yapısı

API Takma Adlarını Kullanma

apis bölümü yapılandırıldığında, komutlarınızda dosya yolu yerine artık main takma adını kullanabilirsiniz:

redocly lint main
redocly stats main
redocly build-docs main

Bu, projenizde birden çok API olduğunda özellikle kullanışlıdır. Herhangi bir argüman olmadan redocly lint komutunu çalıştırırsanız, apis bölümünde tanımlanan tüm API'leri lint edecektir.

Sürekli Entegrasyon (CI)

Redocly CLI'yı CI/CD işlem hattınıza entegre etmek, API kalite kontrollerini otomatikleştirmek için harika bir yoldur. İşte GitHub Actions ile nasıl kullanılacağına dair bir örnek.

.github/workflows/redocly.yaml adında bir dosya oluşturun:

name: Redocly CLI Checks

on:
  push:
    branches: [ main ]
  pull_request:
    branches: [ main ]

jobs:
  lint-and-stats:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout repository
        uses: actions/checkout@v3

      - name: Set up Node.js
        uses: actions/setup-node@v3
        with:
          node-version: '16'

      - name: Install Redocly CLI
        run: npm install -g @redocly/cli@latest

      - name: Lint API definition
        run: redocly lint openapi.yaml --format=github-actions

      - name: Get API stats
        run: redocly stats openapi.yaml --format=markdown >> $GITHUB_STEP_SUMMARY

Bu GitHub Actions iş akışı aşağıdakileri yapar:

  1. main dalına yapılan her push ve pull isteğinde tetiklenir.
  2. Kodunuzu kontrol eder.
  3. Node.js ve Redocly CLI'yı kurar.
  4. lint komutunu github-actions formatıyla çalıştırır. Bu, pull isteklerinizdeki tüm sorunları otomatik olarak ek açıklama ile belirtir.
  5. stats komutunu markdown formatıyla çalıştırır ve çıktıyı iş özetine ekler, böylece her çalıştırmada güzel bir rapor elde edersiniz.

Bu, API tanımlarınızın her zaman iyi durumda olduğundan emin olmak için güçlü bir yoldur.

Bölüm 4: Pratik Örnek: Tam Bir İş Akışı

Bu son bölümde, öğrendiğimiz her şeyi bir araya getireceğiz ve eksiksiz, pratik bir iş akışını adım adım inceleyeceğiz. Şunları yapacağız:

  1. Çok dosyalı bir API tanımı ile bir proje yapısı oluşturun.
  2. Bir redocly.yaml yapılandırma dosyası oluşturun.
  3. Özel yapılandırmamızı kullanarak API tanımını lint edin.
  4. API'yi tek bir dosyada bir araya getirin.
  5. API dokümantasyonu oluşturun.

1. Proje Kurulumu

Projemiz için yeni bir dizin oluşturalım ve dosya yapısını kuralım.

mkdir redocly-petstore
cd redocly-petstore
mkdir -p openapi/components/schemas openapi/paths

Şimdi, bölünmüş API dosyalarını oluşturalım.

openapi/components/schemas/Pet.yaml:

type: object
properties:
  id:
    type: integer
    format: int64
  name:
    type: string
  tag:
    type: string

openapi/paths/pets.yaml:

get:
  summary: List all pets
  operationId: listPets
  responses:
    '200':
      description: An array of pets.
      content:
        application/json:
          schema:
            type: array
            items:
              $ref: ../components/schemas/Pet.yaml

openapi/root.yaml (ana giriş noktamız):

openapi: 3.0.0
info:
  title: Petstore API
  version: 1.0.0
  description: A professional API for managing pets.
servers:
  - url: <https://api.petstore.com/v1>
paths:
  /pets:
    $ref: ./paths/pets.yaml

2. redocly.yaml Oluşturma

Şimdi, redocly-petstore dizininin kökünde yapılandırma dosyamızı oluşturalım.

redocly.yaml:

apis:
  petstore@v1:
    root: openapi/root.yaml

lint:
  extends:
    - recommended
  rules:
    operation-summary: error
    no-path-trailing-slash: warn
    tag-description: error

Bu yapılandırmada, API'miz için petstore@v1 takma adını tanımladık ve bazı özel linting kuralları ekledik.

3. API'yi Lint Etme

Şimdi, yeni yapılandırmamızı kullanarak API'mizi lint edelim.

redocly lint petstore@v1

API'miz henüz tüm yeni kurallarımıza uymadığı için bazı hatalar ve uyarılar göreceksiniz. Örneğin, açıklamalı etiketlerimiz yok. Bu, kendi API stil rehberinizi nasıl uygulayabileceğinizi gösterir.

4. API'yi Bir Araya Getirme (Bundle)

Ardından, çok dosyalı API'mizi tek bir dağıtılabilir dosyada bir araya getirelim.

redocly bundle petstore@v1 -o dist/petstore.yaml

Bu, içinde tamamen çözülmüş API tanımını içeren bir petstore.yaml dosyasıyla birlikte bir dist dizini oluşturacaktır.

5. Dokümantasyon Oluşturma

Son olarak, API dokümantasyonumuzu oluşturalım.

redocly build-docs petstore@v1 -o dist/petstore-docs.html

Bu, dist/petstore-docs.html dosyasını oluşturacaktır. Güzel, etkileşimli API dokümantasyonunuzu görmek için bu dosyayı tarayıcınızda açın.

Ve işte! Yapılandırılmış, çok dosyalı bir API tanımından, bir araya getirilmiş bir dosyaya ve profesyonel dokümantasyona kadar eksiksiz bir iş akışı, hepsi Redocly CLI ile yönetiliyor.

Sonuç

Bu eğitimde, Redocly CLI'ya derinlemesine bir dalış yaptık. Kurulumun temelleri ve temel komutlarla başladık, ardından yapılandırma ve CI entegrasyonu gibi gelişmiş konulara geçtik ve son olarak eksiksiz, pratik bir iş akışını adım adım inceledik.

Artık Redocly CLI'yı nasıl kullanacağınıza dair sağlam bir anlayışa sahip olmalısınız:

Redocly CLI, API geliştirme iş akışınızı önemli ölçüde iyileştirebilecek çok yönlü ve güçlü bir araçtır. Özelliklerini daha fazla keşfetmenizi ve projelerinize entegre etmenizi öneririm.

Ek Kaynaklar

Bu eğitimi takip ettiğiniz için teşekkür ederim. Mutlu API oluşturmalar!

💡
Oluşturan harika bir API Test aracı mı istiyorsunuz güzel API Dokümantasyonu?

Geliştirici Ekibinizin birlikte çalışması için entegre, Hepsi Bir Arada bir platform mu istiyorsunuz maksimum üretkenlik?

Apidog tüm taleplerinizi karşılar ve Postman'ı çok daha uygun bir fiyata değiştirir!
button

API Tasarım-Öncelikli Yaklaşımı Apidog'da Uygulayın

API'leri oluşturmanın ve kullanmanın daha kolay yolunu keşfedin

Ücretsiz Kaydolİndir