Blog

Redocly CLIの使い方：Redoclyチュートリアル

Mark Ponomarev

Mark Ponomarev

9 6月 2025

Redocly CLIの使い方：Redoclyチュートリアル

Redocly CLIに関する包括的なチュートリアルへようこそ！Redocly CLIは、OpenAPIおよびSwagger定義のための強力なオールインワンコマンドラインツールです。APIライフサイクル全体を通して、API記述の構築、管理、品質チェックを支援します。開発者、テクニカルライター、APIプロダクトマネージャーのいずれであっても、このツールはあなたにとって役立つものがあります。

このチュートリアルは、Redocly CLIを深く掘り下げ、初心者から自信を持って使えるユーザーになることを目指しています。インストールから、カスタムリンティングルールやCI/CD統合のような高度な機能まで、すべてをカバーします。このチュートリアルの終わりまでに、Redocly CLIを日常のワークフローに統合し、APIの品質とドキュメントを向上させることができるようになります。

💡
美しいAPIドキュメントを生成する優れたAPIテストツールが必要ですか？

開発チームが最大限の生産性で共同作業できる、統合されたオールインワンプラットフォームが必要ですか？

Apidogはあなたのすべての要求に応え、Postmanをはるかに手頃な価格で置き換えます！
ボタン

Redocly CLIとは？

公式ドキュメントに記載されているように、Redocly CLIはあなたの「オールインワンOpenAPIユーティリティ」です。OpenAPI 3.1、3.0、2.0（レガシーSwagger）、AsyncAPIなどをサポートしています。以下の目的であなたを支援するように設計されています。

このツールは、パフォーマンスとユーザーエクスペリエンスを念頭に置いて構築されており、高速な実行と人間が読みやすいエラーメッセージを提供します。

Redocly CLIを使用する理由

今日のAPIファーストの世界では、高品質なAPI定義を維持することが不可欠です。Redocly CLIは、以下の方法でこれを達成するのに役立ちます。

このチュートリアルで扱う内容

このチュートリアルは、Redocly CLIを習得するためのステップバイステップガイドを提供するように構成されています。扱う内容は以下のとおりです。

さあ、始めましょう！

第1章：Redocly CLIをはじめよう

この章では、Redocly CLIの使用の最初のステップとして、インストールから最初のコマンドの実行までをガイドします。

前提条件

始める前に、システムに以下がインストールされていることを確認してください。

インストール

Redocly CLIをインストールして使用するにはいくつかのオプションがあります。あなたのニーズに最適なものを選択してください。

npxの使用（クイック使用に推奨）

グローバルインストールなしでRedocly CLIを試してみたい場合は、npmパッケージランナーであるnpxを使用できます。このコマンドは、Redocly CLIの最新バージョンをダウンロードして実行します。

npx @redocly/cli@latest --version

任意のredoclyコマンドを使用するには、npx @redocly/cli@latestを先頭に付けます。例：

npx @redocly/cli@latest lint openapi.yaml

これは、CI/CD環境でRedocly CLIを使用する場合や、システムをグローバルパッケージで煩雑にしたくない場合に最適な方法です。

npmによるグローバルインストール

定期的に使用する場合は、グローバルインストールの方が便利です。これにより、redoclyコマンドがターミナルで直接利用可能になります。

npm install -g @redocly/cli@latest

インストール後、バージョンを確認することで検証できます。

redocly --version

これで、次のようにコマンドを実行できます。

redocly lint openapi.yaml

Dockerの使用

Dockerを使用したい場合は、Redoclyが事前に構築されたDockerイメージを提供しています。これは、ツールをローカル環境から隔離するのに役立ちます。

まず、Docker Hubからイメージをプルします。

docker pull redocly/cli

コマンドを実行するには、現在の作業ディレクトリ（APIファイルがある場所）をボリュームとしてDockerコンテナにマウントする必要があります。

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

このコマンドでは、$PWDは現在のディレクトリを指し、コンテナ内の/specディレクトリにマウントされます。その後、/specパスを使用してファイルを参照する必要があります。

基本的なコマンド構造

Redocly CLIを使用するための基本的な構造は次のとおりです。

redocly [command] [arguments] [options]

特定のコマンドのヘルプは、--helpオプションを使用することでいつでも取得できます。

redocly lint --help

Redocly CLIがインストールされ、基本的なコマンド構造を理解できたので、その強力な機能を探索に進みましょう。

第2章：コアコマンドと機能

この章では、Redocly CLIのコアコマンドを扱います。API定義のリンティング、管理、ドキュメント化、分析方法を探求します。この章の例では、シンプルなopenapi.yamlファイルを使用します。

以下の内容でopenapi.yamlという名前のファイルを作成しましょう。

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

セクション2.1：API記述のリンティング（lint）

APIリンティングは、API定義ファイルの一貫性、正確性、スタイルをチェックするプロセスです。API設計ガイドラインを強制し、本番環境に到達する前に潜在的な問題を検出するのに役立ちます。

基本的な使用法

lintコマンドは、API定義をルールセットに対してチェックするために使用されます。

redocly lint openapi.yaml

デフォルトでは、redocly lintはrecommendedルールセットを使用します。openapi.yamlに問題がある場合、出力はそれらを詳細に示します。私たちの例のファイルの場合、出力は次のようになります。

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

Woohoo! Your API description is valid. 🎉

ルールの設定

Redocly CLIには、設定可能な3つの組み込みルールセットが付属しています。

--extendsオプションを使用してルールセットを指定できます。

redocly lint openapi.yaml --extends=minimal

redocly.yaml設定ファイルで独自のカスタムルールセットを作成することもできます。これについては第3章で説明します。

出力フォーマット

lintコマンドは、--formatオプションを使用してさまざまな出力フォーマットをサポートしており、これは他のツールとの統合に非常に役立ちます。

stylishフォーマットの使用例：

redocly lint openapi.yaml --format=stylish

問題の無視

特定の問題を無視する必要がある場合があります。エラーや警告を抑制するために、.redocly.lint-ignore.yamlファイルを生成できます。

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

このコマンドは無視ファイルを作成します。再度lintを実行すると、このファイルにリストされている問題は無視されます。これにより、リンティングプロセスをきめ細かく制御できます。

セクション2.2：bundleとsplitによるAPI記述の管理

APIが成長するにつれて、単一のモノリシックなOpenAPIファイルを管理するのは煩雑になります。Redocly CLIは、これを支援するためにsplitとbundleという2つのコマンドを提供しています。

大きなOpenAPIファイルの分割（split）

splitコマンドを使用すると、大きなAPI定義ファイルを、より管理しやすい複数のファイル構造に分割できます。コンポーネント、パス、例を個別のファイルやフォルダに抽出します。

openapi.yamlを分割しましょう。

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

このコマンドは、以下の構造を持つsplit-apiディレクトリを作成します。

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

split-api内の新しいopenapi.yamlは、外部ファイルへのリンクに$refを使用するようになります。

# 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

複数のファイルのバンドル（bundle）

bundleコマンドはsplitの逆を行います。ルートAPI定義ファイルを受け取り、すべてのローカルな$refを解決して、単一の自己完結型ファイルを作成します。これは、複数のファイル定義をサポートしないツールに役立ちます。

分割したAPIを単一のファイルにバンドルし直しましょう。

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

bundled-api.yamlは、元のopenapi.yamlと同じ内容になります。

デリファレンシング

bundleコマンドは、すべての$ref（リモートのものを含む）が解決され、その内容に置き換えられた完全にデリファレンスされたファイルを作成することもできます。

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

これは便利ですが、ファイルが非常に大きくなる可能性があり、循環参照がJSON出力で問題を引き起こす可能性があることに注意してください。

セクション2.3：APIドキュメントの生成（build-docs）

Redocly CLIの最も強力な機能の1つは、オープンソースのRedocエンジンを使用して、美しくインタラクティブなAPIリファレンスドキュメントを生成する機能です。

基本的な使用法

ドキュメントを生成するには、build-docsコマンドを使用します。

redocly build-docs openapi.yaml

これにより、現在のディレクトリにredoc-static.htmlファイルが作成されます。ブラウザで開いてドキュメントを確認してください。

-oまたは--outputオプションを使用して、別の出力ファイルを指定できます。

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

出力のカスタマイズ

--theme.openapiオプションを使用して、ドキュメントの外観をカスタマイズできます。これにより、色、フォントを変更したり、検索バーなどのUIの一部を無効にしたりできます。

例えば、検索バーを無効にするには：

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

利用可能なすべてのテーマオプションは、公式のRedoclyドキュメントで見つけることができます。

さらに細かく制御したい場合は、独自のHandlebarsテンプレートを提供してドキュメントをレンダリングできます。これは、HTML出力の完全なカスタマイズを可能にする高度な機能です。

セクション2.4：API統計情報の取得（stats）

statsコマンドは、パス、操作、スキーマの数など、API定義に関する有用なメトリックを提供します。

統計情報の取得方法

APIの統計情報を取得するには、単に以下を実行します。

redocly stats openapi.yaml

デフォルトの出力は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

異なるフォーマット

lintコマンドと同様に、statsは--formatオプションを使用して異なる出力フォーマットをサポートしています。jsonおよびmarkdownフォーマットは特に便利です。

redocly stats openapi.yaml --format=json

これは、統計情報を他のツールやダッシュボードに取り込むのに最適です。

redocly stats openapi.yaml --format=markdown

これはMarkdownテーブルを生成し、レポートやGitHub Actionsのサマリーでの使用に最適です。これについては次の章で説明します。

第3章：高度なトピック

この章では、強力な設定ファイルやCI/CDパイプラインとの統合など、Redocly CLIのより高度な機能について深く掘り下げます。

設定ファイル（redocly.yaml）

Redocly CLIは完全にコマンドラインから使用できますが、redocly.yaml設定ファイルを使用すると、設定を1か所に保存でき、コマンドを短くし、設定を再利用可能にできます。

プロジェクトのルートにredocly.yamlファイルを作成しましょう。

# 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

設定ファイルの構造

APIエイリアスの使用

apisセクションを設定すると、コマンドでファイルパスの代わりにエイリアスmainを使用できるようになります。

redocly lint main
redocly stats main
redocly build-docs main

これは、プロジェクトに複数のAPIがある場合に特に便利です。引数なしでredocly lintを実行すると、apisセクションで定義されているすべてのAPIがリンティングされます。

継続的インテグレーション（CI）

Redocly CLIをCI/CDパイプラインに統合することは、API品質チェックを自動化するための素晴らしい方法です。GitHub Actionsと組み合わせて使用する例を以下に示します。

.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

このGitHub Actionsワークフローは以下を行います。

  1. mainブランチへのすべてのプッシュとプルリクエストでトリガーされます。
  2. コードをチェックアウトします。
  3. Node.jsとRedocly CLIをインストールします。
  4. lintコマンドをgithub-actionsフォーマットで実行します。これにより、プルリクエストで問題が自動的にアノテーションされます。
  5. statsコマンドをmarkdownフォーマットで実行し、出力をジョブサマリーに追加します。これにより、実行ごとに良いレポートが得られます。

これは、API定義が常に良好な状態であることを保証するための強力な方法です。

第4章：実践的な例：完全なワークフロー

この最後の章では、学んだすべてをまとめ、完全な実践的なワークフローを順を追って説明します。以下のことを行います。

  1. 複数のファイルに分かれたAPI定義を持つプロジェクト構造を作成します。
  2. redocly.yaml設定ファイルを作成します。
  3. カスタム設定を使用してAPI定義をリンティングします。
  4. APIを単一のファイルにバンドルします。
  5. APIドキュメントを生成します。

1. プロジェクトのセットアップ

プロジェクト用の新しいディレクトリを作成し、ファイル構造をセットアップしましょう。

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

次に、分割されたAPIファイルを作成しましょう。

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（メインエントリポイント）：

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の作成

次に、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

この設定では、APIのエイリアスpetstore@v1を定義し、いくつかのカスタムリンティングルールを追加しました。

3. APIのリンティング

さあ、新しい設定を使用してAPIをリンティングしましょう。

redocly lint petstore@v1

APIが新しいルールのすべてにまだ準拠していないため、いくつかのエラーと警告が表示されます。例えば、説明付きのタグがありません。これは、独自のAPIスタイルガイドを強制する方法を示します。

4. APIのバンドル

次に、複数のファイルに分かれたAPIを単一の配布可能なファイルにバンドルしましょう。

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

これにより、完全に解決されたAPI定義を含むpetstore.yamlファイルが内部にあるdistディレクトリが作成されます。

5. ドキュメントの生成

最後に、APIドキュメントを生成しましょう。

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

これにより、dist/petstore-docs.htmlが作成されます。このファイルをブラウザで開いて、美しくインタラクティブなAPIドキュメントを確認してください。

これで完了です！構造化された複数のファイルに分かれたAPI定義から、バンドルされたファイルとプロフェッショナルなドキュメントまで、すべてRedocly CLIで管理される完全なワークフローです。

まとめ

このチュートリアルでは、Redocly CLIについて深く掘り下げました。インストールの基本とコアコマンドから始め、設定やCI統合のような高度なトピックに進み、最後に完全な実践的なワークフローを順を追って説明しました。

これで、Redocly CLIを使用して以下の方法をしっかりと理解できたはずです。

Redocly CLIは、API開発ワークフローを大幅に改善できる多用途で強力なツールです。その機能をさらに探索し、プロジェクトに統合することをお勧めします。

その他のリソース

このチュートリアルをご覧いただきありがとうございました。楽しいAPI構築を！

💡
美しいAPIドキュメントを生成する優れたAPIテストツールが必要ですか？

開発チームが最大限の生産性で共同作業できる、統合されたオールインワンプラットフォームが必要ですか？

Apidogはあなたのすべての要求に応え、Postmanをはるかに手頃な価格で置き換えます！
ボタン

ApidogでAPIデザイン中心のアプローチを取る

APIの開発と利用をよりシンプルなことにする方法を発見できる

無料会員登録ダウンロード