コンテンツにスキップ
Kong Logo | Kong Docs Logo
  • ドキュメント
    • API仕様を確認する
      View all API Specs すべてのAPI仕様を表示 View all API Specs arrow image
    • ドキュメンテーション
      API Specs
      Kong Gateway
      軽量、高速、柔軟なクラウドネイティブAPIゲートウェイ
      Kong Konnect
      SaaSのエンドツーエンド接続のための単一プラットフォーム
      Kong AI Gateway
      GenAI インフラストラクチャ向けマルチ LLM AI Gateway
      Kong Mesh
      Kuma と Envoy をベースにしたエンタープライズサービスメッシュ
      decK
      Kongの構成を宣言型で管理する上で役立ちます
      Kong Ingress Controller
      Kubernetesクラスタ内で動作し、Kongをプロキシトラフィックに設定する
      Kong Gateway Operator
      YAMLマニフェストを使用してKubernetes上のKongデプロイメントを管理する
      Insomnia
      コラボレーティブAPI開発プラットフォーム
  • Plugin Hub
    • Plugin Hubを探索する
      View all plugins すべてのプラグインを表示 View all plugins arrow image
    • 機能性 すべて表示 View all arrow image
      すべてのプラグインを表示
      AI's icon
      AI
      マルチ LLM AI Gatewayプラグインを使用してAIトラフィックを管理、保護、制御する
      認証's icon
      認証
      認証レイヤーでサービスを保護する
      セキュリティ's icon
      セキュリティ
      追加のセキュリティレイヤーでサービスを保護する
      トラフィック制御's icon
      トラフィック制御
      インバウンドおよびアウトバウンドAPIトラフィックの管理、スロットル、制限
      サーバーレス's icon
      サーバーレス
      他のプラグインと組み合わせてサーバーレス関数を呼び出します
      分析と監視's icon
      分析と監視
      APIとマイクロサービストラフィックを視覚化、検査、監視
      変革's icon
      変革
      Kongでリクエストとレスポンスをその場で変換
      ログ記録's icon
      ログ記録
      インフラストラクチャに最適なトランスポートを使用して、リクエストと応答データをログに記録します
  • サポート
  • コミュニティ
  • Kongアカデミー
デモを見る 無料トライアルを開始
decK
  • Home icon
  • decK
  • File
  • openapi2kong
report-issue問題を報告する
  • Kong Gateway
  • Kong Konnect
  • Kong Mesh
  • Kong AI Gateway
  • Plugin Hub
  • decK
  • Kong Ingress Controller
  • Kong Gateway Operator
  • Insomnia
  • Kuma

  • ドキュメント投稿ガイドライン
  • Introduction
    • Overview
    • Configuration Options
    • Support Policy
    • Security Policy
  • Changelog
  • Installation
    • Overview
    • Binary
    • Docker
    • GitHub Actions
  • Get Started
  • Managing Kong Gateway
    • Overview
    • Konnect Configuration
    • Configure Authentication
    • Ping
    • Backup
    • Diff
    • Sync
    • Apply
    • Reset
    • Validate
    • RBAC
    • Workspaces
    • Tags
    • De-duplicate Plugin Configuration
    • Object Defaults
    • Sensitive Data
  • decK Files
    • Overview
    • Config Generation
      • openapi2kong
      • kong2kic
      • kong2tf
    • Linting
    • File Manipulation
      • Overview
      • Update Values
      • Plugins
      • Tags
      • Namespace
    • Combining Files
      • Merge
      • Render
    • Validate
    • Convert
  • APIOps
    • Overview
    • Continuous Integration
    • Federated Config
  • Reference
    • Entities
    • FAQ
    • Gateway 3.0 Upgrade
    • Environment Variables
enterprise-switcher-icon 次に切り替える: OSS
On this pageOn this page
  • Get started
  • Best practices
    • ID Generation
    • Adding plugins
  • Custom x-kong extensions

このページは、まだ日本語ではご利用いただけません。翻訳中です。

openapi2kong

The openapi2kong command converts an OpenAPI specification to Kong’s declarative configuration format.

  • A Service is created, pointing to the URLs in the servers block
  • One route per operationId is created
  • If an openIdConnect securityScheme is present, an openid-connect plugin will be generated

Get started

Converting an OpenAPI file to a Kong declarative configuration can be done in a single command:

deck file openapi2kong --spec oas.yaml --output-file kong.yaml

Best practices

ID Generation

The openapi2kong command will generate a declarative configuration file that contains an id for each entity. This ensures that even if the entity name (or any other identifying parameter) changes, it will update an entity in Kong Gateway rather than deleting then recreating an entity.

If you have an existing Kong Gateway instance, you can use the --inso-compatible flag to skip ID generation. In this instance, decK will match entities on a best effort basis using the name field.

If you have multiple teams using the same names and operationId values in their specifications, you can specify the --uuid-base flag to set a custom namespace when generating IDs.

To learn more about ID generation, see the openapi2kong GitHub documentation.

Adding plugins

openapi2kong allows you to configure plugins directly in your OpenAPI specification by providing an x-kong-plugin-PLUGIN-NAME annotation at the root level to add it to the service, at the path level to add it to all routes on that path, or on an operation to add it to a specific route.

However, we do not recommend using this functionality. Routing and policy enforcement are generally owned by different teams, and you do not want to publish plugin configuration in an OpenAPI specification that is shared with customers.

We recommend using the add-plugin command after the openapi2kong command has been run.

If you really want to embed plugin configuration in your OpenAPI specification, here is an example extension that adds the request-termination plugin to a route:

x-kong-request-termination:
  status_code: 403
  message: So long and thanks for all the fish!

There are two exceptions to this recommendation:

  • Configuring OpenID Connect scopes
  • Dynamically generating request validator plugins for all endpoints

Configuring OpenID Connect scopes

OpenID Connect allows you to check for specific scopes when accessing a route. App development teams know which scopes are required for the paths their application serves.

To define scopes on a per-path level, use the x-kong-security-openid-connect annotation at the same level as operationId.

x-kong-security-openid-connect:
  config:
    scopes_required: ["scope1", "scope2"]

Dynamic request-validator plugin configuration

The Kong request-validator plugin can validate incoming requests against a user-provided JSON schema.

The plugin can be configured manually, but openapi2kong can use the provided OpenAPI specification to configure the request-validator plugin for all routes automatically. To enable this behavior, add the x-kong-plugin-request-validator at the root level to add it to all routes, at the path level to add it to all routes on that path, or on an operation to add it to a specific route.

Omitting the body_schema and parameter_schema configuration options tells openapi2kong to automatically inject the schema for the current endpoint when generating a Kong Gateway declarative configuration file.

x-kong-plugin-request-validator:
  config:
    verbose_response: true

Custom x-kong extensions

The openapi2kong command supports the following custom x-kong extensions to customize the declarative configuration file generation:

Annotation Description
x-kong-tags Specify the tags to use for each Kong Gateway entity generated. Tags can be overridden when doing the conversion. This can only be specified at the document level.
x-kong-service-defaults The defaults for the services generated from the servers object in the OpenAPI spec. These defaults can also be added to the path and operation objects, which will generate a new service entity.
x-kong-upstream-defaults The defaults for upstreams generated from the servers object in the OpenAPI spec. These defaults can also be added to the path and operation objects, which will generate a new service entity.
x-kong-route-defaults The defaults for the routes generated from paths in the OpenAPI spec.
x-kong-name The name for the entire spec file. This is used for naming the service and upstream objects in Kong Gateway. If not given, it will use the info.title field to name these objects, or a random UUID if the info.title field is missing. Names are converted into valid identifiers. This directive can also be used on path and operation objects to name them. Similarly to operationId, each x-kong-name must be unique within the spec file.
x-kong-plugin-<kong-plugin-name> Directive to add a plugin. The plugin name is derived from the extension name and is a generic mechanism that can add any type of plugin. This plugin is configured on a global level for the OpenAPI spec. As such, it is configured on the service entity, and applies on all paths and operations in this spec.

The plugin name can also be specified on paths and operations to override the config for that specific subset of the spec. In that case, it is added to the generated route entity. If new service entities are generated from path or operation objects, the plugins are copied over accordingly (for example, by having servers objects, or upstream or service defaults specified on those levels).

A consumer can be referenced by setting the consumer field to the consumer name or ID.

Note: Since the plugin name is in the key, only one instance of each plugin can be added at each level.
securitySchemes.[...].x-kong-security-openid-connect Specifies that the OpenID Connect plugin is to be used to implement this security scheme object. Any custom configuration can be added as usual for plugins.
components.x-kong Reusable Kong Gateway configuration components. All x-kong references must be under this key. It accepts the following referenceable elements:
• x-kong-service-defaults
• x-kong-upstream-defaults
• x-kong-route-defaults
• x-kong-plugin-[...] plugin configurations
• x-kong-security-[...] plugin configurations

For more information and examples of these annotations, see the commented example openapi2kong OAS.

Thank you for your feedback.
Was this page useful?
情報が多すぎる場合 close cta icon
Kong Konnectを使用すると、より多くの機能とより少ないインフラストラクチャを実現できます。月額1Mリクエストが無料。
無料でお試しください
  • Kong
    APIの世界を動かす

    APIマネジメント、サービスメッシュ、イングレスコントローラーの統合プラットフォームにより、開発者の生産性、セキュリティ、パフォーマンスを大幅に向上します。

    • 製品
      • Kong Konnect
      • Kong Gateway Enterprise
      • Kong Gateway
      • Kong Mesh
      • Kong Ingress Controller
      • Kong Insomnia
      • 製品アップデート
      • 始める
    • ドキュメンテーション
      • Kong Konnectドキュメント
      • Kong Gatewayドキュメント
      • Kong Meshドキュメント
      • Kong Insomniaドキュメント
      • Kong Konnect Plugin Hub
    • オープンソース
      • Kong Gateway
      • Kuma
      • Insomnia
      • Kongコミュニティ
    • 会社概要
      • Kongについて
      • お客様
      • キャリア
      • プレス
      • イベント
      • お問い合わせ
  • 利用規約• プライバシー• 信頼とコンプライアンス
© Kong Inc. 2025