Blog

Tutorial Redocly: Cara Menggunakan Redocly CLI

Mark Ponomarev

Mark Ponomarev

9 June 2025

Tutorial Redocly: Cara Menggunakan Redocly CLI

Selamat datang di tutorial komprehensif tentang Redocly CLI! Redocly CLI adalah alat baris perintah yang kuat dan serba guna untuk definisi OpenAPI dan Swagger. Ini membantu Anda membangun, mengelola, dan memeriksa kualitas deskripsi API Anda di seluruh siklus hidup API. Baik Anda seorang developer, technical writer, atau API product manager, alat ini memiliki sesuatu untuk Anda.

Tutorial ini bertujuan untuk menjadi penyelaman mendalam ke dalam Redocly CLI, membawa Anda dari pemula menjadi pengguna yang percaya diri. Kami akan membahas segalanya mulai dari instalasi hingga fitur-fitur canggih seperti aturan linting kustom dan integrasi CI/CD. Di akhir tutorial ini, Anda akan dapat mengintegrasikan Redocly CLI ke dalam alur kerja harian Anda untuk meningkatkan kualitas dan dokumentasi API Anda.

💡
Ingin alat Pengujian API yang hebat yang menghasilkan Dokumentasi API yang indah?

Ingin platform terintegrasi, All-in-One untuk Tim Developer Anda bekerja sama dengan produktivitas maksimum?

Apidog memenuhi semua kebutuhan Anda, dan menggantikan Postman dengan harga yang jauh lebih terjangkau!
button

Apa itu Redocly CLI?

Seperti yang disebutkan dalam dokumentasi resminya, Redocly CLI adalah "utilitas OpenAPI serba guna" Anda. Ini mendukung OpenAPI 3.1, 3.0, 2.0 (Swagger lama), AsyncAPI, dan lainnya. Ini dirancang untuk membantu Anda dengan:

Alat ini dibangun dengan mempertimbangkan kinerja dan pengalaman pengguna, menyediakan eksekusi cepat dan pesan kesalahan yang mudah dibaca.

Mengapa Menggunakan Redocly CLI?

Di dunia yang mengutamakan API saat ini, menjaga definisi API berkualitas tinggi sangat penting. Redocly CLI membantu Anda mencapai ini dengan:

Apa yang Akan Dibahas Tutorial Ini

Tutorial ini disusun untuk memberikan panduan langkah demi langkah untuk menguasai Redocly CLI. Berikut adalah apa yang akan kita bahas:

Mari kita mulai!

Bab 1: Memulai dengan Redocly CLI

Bab ini akan memandu Anda melalui langkah-langkah pertama penggunaan Redocly CLI, mulai dari instalasi hingga menjalankan perintah pertama Anda.

Prasyarat

Sebelum memulai, pastikan Anda memiliki hal-hal berikut terinstal di sistem Anda:

Instalasi

Anda memiliki beberapa opsi untuk menginstal dan menggunakan Redocly CLI. Pilih salah satu yang paling sesuai dengan kebutuhan Anda.

Menggunakan npx (Direkomendasikan untuk penggunaan cepat)

Jika Anda hanya ingin mencoba Redocly CLI tanpa instalasi global, Anda dapat menggunakan npx, runner paket npm. Perintah ini akan mengunduh dan menjalankan versi terbaru Redocly CLI.

npx @redocly/cli@latest --version

Untuk menggunakan perintah redocly apa pun, cukup tambahkan npx @redocly/cli@latest di depannya. Contoh:

npx @redocly/cli@latest lint openapi.yaml

Ini adalah cara yang bagus untuk menggunakan Redocly CLI di lingkungan CI/CD atau jika Anda tidak ingin membebani sistem Anda dengan paket global.

Instalasi Global dengan npm

Untuk penggunaan rutin, instalasi global lebih nyaman. Ini membuat perintah redocly langsung tersedia di terminal Anda.

npm install -g @redocly/cli@latest

Setelah instalasi, Anda dapat memverifikasinya dengan memeriksa versinya:

redocly --version

Sekarang Anda dapat menjalankan perintah seperti ini:

redocly lint openapi.yaml

Menggunakan Docker

Jika Anda lebih suka menggunakan Docker, Redocly menyediakan image Docker yang sudah dibuat sebelumnya. Ini berguna untuk mengisolasi alat dari lingkungan lokal Anda.

Pertama, tarik image dari Docker Hub:

docker pull redocly/cli

Untuk menjalankan perintah, Anda perlu me-mount direktori kerja saat ini (tempat file API Anda berada) sebagai volume ke container Docker.

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

Dalam perintah ini, $PWD mengacu pada direktori Anda saat ini, yang di-mount ke direktori /spec di dalam container. Anda kemudian perlu merujuk file Anda menggunakan path /spec.

Struktur Perintah Dasar

Struktur dasar untuk menggunakan Redocly CLI adalah:

redocly [perintah] [argumen] [opsi]

Anda selalu bisa mendapatkan bantuan untuk perintah tertentu dengan menggunakan opsi --help:

redocly lint --help

Sekarang setelah Anda menginstal Redocly CLI dan memahami struktur perintah dasarnya, mari kita lanjutkan untuk menjelajahi fitur-fiturnya yang kuat.

Bab 2: Perintah dan Fitur Inti

Bab ini mencakup perintah inti Redocly CLI. Kami akan menjelajahi cara melakukan linting, mengelola, mendokumentasikan, dan menganalisis definisi API Anda. Untuk contoh dalam bab ini, kami akan menggunakan file openapi.yaml sederhana.

Mari kita buat file bernama openapi.yaml dengan konten berikut:

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

Bagian 2.1: Melakukan Linting Deskripsi API Anda (lint)

Linting API adalah proses pemeriksaan file definisi API Anda untuk konsistensi, kebenaran, dan gaya. Ini membantu Anda menerapkan panduan desain API dan menangkap masalah potensial sebelum mencapai produksi.

Penggunaan Dasar

Perintah lint digunakan untuk memeriksa definisi API Anda terhadap serangkaian aturan.

redocly lint openapi.yaml

Secara default, redocly lint menggunakan ruleset recommended. Jika openapi.yaml kita memiliki masalah, output akan merincinya. Untuk file contoh kita, output seharusnya:

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

Woohoo! Your API description is valid. 🎉

Mengonfigurasi Aturan

Redocly CLI dilengkapi dengan tiga ruleset bawaan yang dapat dikonfigurasi:

Anda dapat menentukan ruleset dengan opsi --extends:

redocly lint openapi.yaml --extends=minimal

Anda juga dapat membuat ruleset kustom Anda sendiri dalam file konfigurasi redocly.yaml. Kami akan membahas ini di Bab 3.

Format Output

Perintah lint mendukung berbagai format output menggunakan opsi --format, yang sangat berguna untuk berintegrasi dengan alat lain.

Contoh penggunaan format stylish:

redocly lint openapi.yaml --format=stylish

Mengabaikan Masalah

Terkadang Anda mungkin perlu mengabaikan masalah tertentu. Anda dapat menghasilkan file .redocly.lint-ignore.yaml untuk menekan kesalahan dan peringatan.

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

Perintah ini akan membuat file ignore. Jika Anda menjalankan lint lagi, masalah yang tercantum dalam file ini akan diabaikan. Ini memberi Anda kontrol granular atas proses linting.

Bagian 2.2: Mengelola Deskripsi API dengan bundle dan split

Seiring pertumbuhan API Anda, mengelola satu file OpenAPI yang monolitik menjadi rumit. Redocly CLI menyediakan dua perintah untuk membantu ini: split dan bundle.

Memecah File OpenAPI Besar (split)

Perintah split memungkinkan Anda memecah file definisi API besar menjadi struktur multi-file yang lebih mudah dikelola. Ini mengekstrak komponen, path, dan contoh ke dalam file dan folder terpisah.

Mari kita pecah openapi.yaml kita:

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

Perintah ini akan membuat direktori split-api dengan struktur berikut:

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

openapi.yaml baru di split-api sekarang akan menggunakan $ref untuk menautkan ke file eksternal:

# 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

Ini membuatnya jauh lebih mudah untuk mengelola bagian-bagian API Anda yang berbeda.

Menggabungkan Beberapa File (bundle)

Perintah bundle melakukan kebalikan dari split. Ini mengambil file definisi API root dan menyelesaikan semua $ref lokal untuk membuat file tunggal yang mandiri. Ini berguna untuk alat yang tidak mendukung definisi multi-file.

Mari kita gabungkan API kita yang terpecah kembali menjadi satu file:

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

bundled-api.yaml akan memiliki konten yang sama dengan openapi.yaml asli kita.

Dereferencing

Perintah bundle juga dapat membuat file yang sepenuhnya dereferensi, di mana semua $ref (termasuk yang remote) diselesaikan dan diganti dengan kontennya.

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

Ini bisa berguna, tetapi perlu diketahui bahwa ini dapat membuat file jauh lebih besar dan bahwa referensi melingkar dapat menyebabkan masalah dengan output JSON.

Bagian 2.3: Menghasilkan Dokumentasi API (build-docs)

Salah satu fitur paling kuat dari Redocly CLI adalah kemampuannya untuk menghasilkan dokumentasi referensi API yang indah dan interaktif menggunakan mesin Redoc open-source.

Penggunaan Dasar

Untuk menghasilkan dokumentasi, gunakan perintah build-docs:

redocly build-docs openapi.yaml

Ini akan membuat file redoc-static.html di direktori Anda saat ini. Buka di browser Anda untuk melihat dokumentasi Anda.

Anda dapat menentukan file output yang berbeda dengan opsi -o atau --output:

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

Menyesuaikan Output

Anda dapat menyesuaikan tampilan dan nuansa dokumentasi Anda menggunakan opsi --theme.openapi. Ini memungkinkan Anda mengubah warna, font, dan bahkan menonaktifkan bagian UI seperti bilah pencarian.

Misalnya, untuk menonaktifkan bilah pencarian:

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

Anda dapat menemukan semua opsi tema yang tersedia dalam dokumentasi resmi Redocly.

Untuk kontrol yang lebih besar, Anda dapat menyediakan template Handlebars Anda sendiri untuk merender dokumentasi. Ini adalah fitur lanjutan yang memungkinkan kustomisasi lengkap output HTML.

Bagian 2.4: Mendapatkan Statistik API (stats)

Perintah stats menyediakan metrik yang berguna tentang definisi API Anda, seperti jumlah path, operasi, skema, dan lainnya.

Cara Mendapatkan Statistik

Untuk mendapatkan statistik untuk API Anda, cukup jalankan:

redocly stats openapi.yaml

Output default adalah dalam format stylish:

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

Format Berbeda

Seperti perintah lint, stats mendukung format output yang berbeda dengan opsi --format. Format json dan markdown sangat berguna.

redocly stats openapi.yaml --format=json

Ini bagus untuk memasukkan statistik ke dalam alat atau dashboard lain.

redocly stats openapi.yaml --format=markdown

Ini menghasilkan tabel Markdown, yang sempurna untuk laporan atau untuk digunakan dalam ringkasan GitHub Actions, seperti yang akan kita lihat di bab berikutnya.

Bab 3: Topik Lanjutan

Dalam bab ini, kita akan menyelami beberapa fitur Redocly CLI yang lebih canggih, termasuk file konfigurasi yang kuat dan integrasi dengan pipeline CI/CD.

File Konfigurasi (redocly.yaml)

Meskipun Anda dapat menggunakan Redocly CLI sepenuhnya dari baris perintah, file konfigurasi redocly.yaml memungkinkan Anda menyimpan konfigurasi Anda di satu tempat, membuat perintah Anda lebih pendek dan konfigurasi Anda dapat digunakan kembali.

Mari kita buat file redocly.yaml di root proyek kita:

# redocly.yaml

# Ini adalah file konfigurasi contoh.
# Untuk daftar lengkap opsi, lihat dokumentasi Redocly.

apis:
  main:
    root: openapi.yaml

lint:
  extends:
    - recommended
  rules:
    # Anda dapat menyesuaikan aturan di sini.
    # Misalnya, pastikan semua operasi memiliki ringkasan.
    operation-summary: error

Struktur File Konfigurasi

Menggunakan Alias API

Dengan bagian apis yang dikonfigurasi, Anda sekarang dapat menggunakan alias main alih-alih path file dalam perintah Anda:

redocly lint main
redocly stats main
redocly build-docs main

Ini sangat berguna ketika Anda memiliki beberapa API dalam proyek Anda. Jika Anda menjalankan redocly lint tanpa argumen apa pun, itu akan melakukan linting pada semua API yang didefinisikan di bagian apis.

Integrasi Berkelanjutan (CI)

Mengintegrasikan Redocly CLI ke dalam pipeline CI/CD Anda adalah cara yang fantastis untuk mengotomatiskan pemeriksaan kualitas API. Berikut adalah contoh cara menggunakannya dengan GitHub Actions.

Buat file bernama .github/workflows/redocly.yaml:

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

Alur kerja GitHub Actions ini melakukan hal berikut:

  1. Ini dipicu pada setiap push dan pull request ke branch main.
  2. Ini melakukan checkout kode Anda.
  3. Ini menginstal Node.js dan Redocly CLI.
  4. Ini menjalankan perintah lint dengan format github-actions. Ini akan secara otomatis memberi anotasi pada masalah apa pun langsung di pull request Anda.
  5. Ini menjalankan perintah stats dengan format markdown dan menambahkan output ke ringkasan job, memberi Anda laporan yang bagus di setiap eksekusi.

Ini adalah cara yang ampuh untuk memastikan bahwa definisi API Anda selalu dalam kondisi baik.

Bab 4: Contoh Praktis: Alur Kerja Lengkap

Di bab terakhir ini, kita akan menyatukan semua yang telah kita pelajari dan membahas alur kerja lengkap dan praktis. Kita akan:

  1. Membuat struktur proyek dengan definisi API multi-file.
  2. Membuat file konfigurasi redocly.yaml.
  3. Melakukan linting definisi API menggunakan konfigurasi kustom kita.
  4. Menggabungkan API menjadi satu file.
  5. Menghasilkan dokumentasi API.

1. Penyiapan Proyek

Mari kita buat direktori baru untuk proyek kita dan siapkan struktur file.

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

Sekarang, mari kita buat file API yang terpecah.

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 (titik masuk utama kita):

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. Buat redocly.yaml

Sekarang, mari kita buat file konfigurasi kita di root direktori redocly-petstore.

redocly.yaml:

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

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

Dalam konfigurasi ini, kita telah mendefinisikan alias petstore@v1 untuk API kita dan menambahkan beberapa aturan linting kustom.

3. Lakukan Linting pada API

Sekarang, mari kita lakukan linting pada API kita menggunakan konfigurasi baru kita.

redocly lint petstore@v1

Anda akan melihat beberapa kesalahan dan peringatan karena API kita belum sesuai dengan semua aturan baru kita. Misalnya, kita tidak memiliki tag dengan deskripsi. Ini menunjukkan bagaimana Anda dapat menerapkan panduan gaya API Anda sendiri.

4. Gabungkan API

Selanjutnya, mari kita gabungkan API multi-file kita menjadi satu file yang dapat didistribusikan.

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

Ini akan membuat direktori dist dengan file petstore.yaml di dalamnya, yang berisi definisi API yang sepenuhnya terselesaikan.

5. Hasilkan Dokumentasi

Terakhir, mari kita hasilkan dokumentasi API kita.

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

Ini akan membuat dist/petstore-docs.html. Buka file ini di browser Anda untuk melihat dokumentasi API Anda yang indah dan interaktif.

Dan begitulah! Alur kerja lengkap dari definisi API multi-file yang terstruktur hingga file yang digabungkan dan dokumentasi profesional, semuanya dikelola dengan Redocly CLI.

Kesimpulan

Dalam tutorial ini, kita telah menyelami Redocly CLI secara mendalam. Kita mulai dengan dasar-dasar instalasi dan perintah inti, lalu beralih ke topik lanjutan seperti konfigurasi dan integrasi CI, dan akhirnya membahas alur kerja lengkap dan praktis.

Anda seharusnya sekarang memiliki pemahaman yang kuat tentang cara menggunakan Redocly CLI untuk:

Redocly CLI adalah alat yang serbaguna dan kuat yang dapat secara signifikan meningkatkan alur kerja pengembangan API Anda. Saya mendorong Anda untuk menjelajahi fitur-fiturnya lebih lanjut dan mengintegrasikannya ke dalam proyek Anda.

Sumber Daya Lebih Lanjut

Terima kasih telah mengikuti tutorial ini. Selamat membangun API!

💡
Ingin alat Pengujian API yang hebat yang menghasilkan Dokumentasi API yang indah?

Ingin platform terintegrasi, All-in-One untuk Tim Developer Anda bekerja sama dengan produktivitas maksimum?

Apidog memenuhi semua kebutuhan Anda, dan menggantikan Postman dengan harga yang jauh lebih terjangkau!
button

Mengembangkan API dengan Apidog

Apidog adalah alat pengembangan API yang membantu Anda mengembangkan API dengan lebih mudah dan efisien.

Daftar gratisUnduh