swagmark

OpenAPI YAML から GitHub プレビューで Swagger 風に見える Markdown を生成するツール

概要

swagmark は widdershins のカスタム doT.js テンプレートをコアとし、OpenAPI YAML から以下の特徴を持つ Markdown を生成します。

• HTTP メソッドの色付きバッジ表示
• <details> による折りたたみ可能なエンドポイント（Swagger UI のアコーディオンに近い操作感）
• GFM テーブルによるパラメータ・レスポンス表示
• curl 実行例の自動生成

生成された Markdown は GitHub や VS Code でそのままプレビュー可能です。Swagger UI の完全再現ではなく、Markdown の制約内で最大限 Swagger 風の見た目を実現することを目的としています。

バッジ画像は badgers.space（MIT License）を利用しています。サービス障害時は alt テキスト（例: 🔵 GET）が自動的に表示されます。

出力例

/pets — Create a pet

curl -X POST http://petstore.swagger.io/v1/pets \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -d '{"id":0,"name":"string","tag":"string"}'

Parameters

| Name | In | Type | Required | Description | | --- | --- | --- | --- | --- | | body | body | Pet | true | none | | » id | body | integer(int64) | true | none | | » name | body | string | true | none | | » tag | body | string | false | none |

Responses

| Status | Meaning | Description | Schema | | --- | --- | --- | --- | | 201 | Created | Null response | None | | default | Default | unexpected error | Error |

実際の変換結果は examples/petstore/output/ で確認できます（Petstore OpenAPI を変換したもの）。

インストール・実行

npx（インストール不要）

npx swagmark input.yaml -o docs/

グローバルインストール

npm install -g swagmark
swagmark input.yaml -o docs/

ローカルインストール

npm install --save-dev swagmark

// package.json
{
  "scripts": {
    "docs": "swagmark openapi.yaml -o docs/"
  }
}

使い方

Usage: swagmark [options] <input>

Arguments:
  input                 OpenAPI YAML ファイルまたはディレクトリのパス

Options:
  -o, --output <dir>    出力ディレクトリ（デフォルト: ./output）
  -t, --template <dir>  カスタムテンプレートディレクトリ
  --no-index            README.md（インデックス）の生成をスキップ
  -h, --help            ヘルプを表示
  -v, --version         バージョンを表示

基本的な使い方

# 単一ファイルの変換
swagmark openapi.yaml -o docs/

# ディレクトリ内の全 YAML を一括変換
swagmark openapi/ -o docs/

# カスタムテンプレートを使用
swagmark openapi.yaml -o docs/ --template ./my-templates/

GitHub Actions

# .github/workflows/docs.yml
name: Generate API Docs

on:
  push:
    paths:
      - 'openapi/**'

jobs:
  generate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: rysk-tanaka/swagmark@v0
        with:
          input: './openapi/api.yaml'
          output: './docs/'
      - uses: stefanzweifel/git-auto-commit-action@v5
        with:
          commit_message: 'docs: update API reference'

Docker

docker run --rm \
  -v $(pwd):/work \
  ghcr.io/rysk-tanaka/swagmark \
  /work/openapi.yaml -o /work/docs/

ディレクトリ構造

swagmark/
├── .github/
│   └── workflows/
│       └── auto-release.yml  # リリース + npm + Docker 自動公開
├── action.yml                # GitHub Actions 定義
├── docs/
│   └── design.md             # 設計方針
├── bin/
│   └── cli.js                # CLI エントリポイント（npx 用）
├── examples/
│   └── petstore/             # Petstore サンプル（入力 YAML + 変換結果）
├── src/
│   └── convert.mjs           # 変換ロジック本体
├── templates/
│   └── openapi3/             # カスタム doT.js テンプレート
│       ├── main.dot
│       ├── operation.dot
│       ├── code_shell.dot
│       └── ...（widdershins デフォルトテンプレートからの派生）
├── Dockerfile
├── package.json
├── LICENSE                   # MIT
├── THIRD_PARTY_LICENSES      # widdershins 等の著作権表示
└── README.md

カスタムテンプレート

templates/openapi3/ は widdershins のデフォルトテンプレートをベースに以下をカスタマイズしています。

| テンプレート | 変更内容 | | --- | --- | | operation.dot | エンドポイントを <details>/<summary> で囲む・バッジを追加 | | code_shell.dot | curl 例にリクエストボディ（-d）を追加・不要なコメント行を除去 | | main.dot | HTML タグを Markdown 見出しに置き換え・認証情報をブロッククォートに変換 |

独自テンプレートを使用する場合は --template オプションで指定してください。設計方針の詳細は docs/design.md を参照してください。

既知の問題

punycode モジュールの非推奨警告（Node.js v21 以降）

Node.js v21 以降で実行すると以下の警告が表示されることがあります（v22 LTS を含む）。

(node:12345) [DEP0040] DeprecationWarning: The `punycode` module is deprecated. Please use a userland alternative instead.

これは間接依存（widdershins → markdown-it@10）が Node.js 組み込みの punycode モジュールを使用しているためで、swagmark の動作には影響しません。

• 組み込み punycode は将来のメジャーバージョンで削除予定ですが、現時点ではまだ残存しています
• 警告を抑制するには node --disable-warning=DEP0040 オプションを使用してください

NODE_OPTIONS=--disable-warning=DEP0040 swagmark input.yaml -o docs/

ライセンス

MIT License — © rysk-tanaka

サードパーティのライセンス情報は THIRD_PARTY_LICENSES を参照してください。