Backstage : openapi catalog pluginを導入してみよう

これまで2回にわたってBackstageの基本機能をご紹介してきました。

techblog.ap-com.co.jp techblog.ap-com.co.jp

今回はopenapi catalog pluginを例にして、BackstageのPlugin導入方法をご紹介しましょう。

OpenAPI Catalog Pluginのご紹介

いきなりOpenAPI Catalog Pluginの表示結果のご紹介です。

APIを登録しようとするリポジトリにはOpenAPIの定義yamlファイルが存在しています。これをBackstage側に取り込み、Backstage内に表示できるようになります。

複数チームで開発しているシステムの場合、こうしたAPIの定義を共有しておくことが重要になります。どうなっているかをわざわざそのチームに確認したり、開発リポジトリの中を確認しなくてもBackstage上でOpenAPI定義を見ることができます。

OpenAPIを使って開発したことある方ならお気づきとは思いますが、表示されている画面はSwaggerの画面そのものですから、公開されているAPIであればBackstage上でかんたんなAPI動作確認も行うことができます。

またひとつ開発作業が少しだけ簡単になったのではないでしょうか。

それではこの機能をどのように実現したかを紹介していきましょう

実装方法

前提

ご存知の方もいらっしゃると思いますが、Backstageはそれぞれの環境用に初期コードを用意し、そのコードを修正していくことでPluginを導入していきます。

手順は公式ページを御覧ください。ここではポイントだけご紹介します。 Backstageを利用する際に一番最初にするコマンドが次のものです。

npx @backstage/create-app@latest

このコマンドで実行に必要なコード一式がローカルディスクにコピーされます。いくつかフォルダが作成視されますが、本体はpackagesフォルダにあり、その下でappsフォルダにReactベースのSPAアプリケーション、backendフォルダにExpressJSベースのバックエンドアプリケーションのコードができあがります。

今回はこうしたコード生成や、その後のサインイン環境等のコンフィグレーションが環境した状態であることを前提とします。

Pluginの導入

通常PluginはBackstage Webサイト上のPluginのページに掲載されているのですが、今回今回導入するOpenAPI Catalog Pluginの導入手順は backstageのGitHubリポジトリ内で見ることができます。

基本的にWebサイト、またはリポジトリのREADMEに導入方法が記載されているのでそれに従って修正していけばよいのでそれほど難しい作業ではありません。

今回の場合は以下のような手順になります。

プラグインモジュールのインストール

yarnコマンドでモジュールを追加します。

yarn add --cwd packages/backend @backstage/plugin-catalog-backend-module-openapi

完了したら packages/appやpackages/backend下にあるコードを修正します。今回の場合 packages/backend/src/plugins/catalog.ts というファイルを修正します。

修正内容はREADMEに記載されているとおりで今回の場合は下記の２行を追加します。

import { jsonSchemaRefPlaceholderResolver } from '@backstage/plugin-catalog-backend-module-openapi'


  builder.setPlaceholderResolver('openapi', jsonSchemaRefPlaceholderResolver); 
  builder.setPlaceholderResolver('asyncapi', jsonSchemaRefPlaceholderResolver);

以上で終了です。

Catalog-infoへの設定追加

続いて、OpenAPI情報を登録したいリポジトリのcatalog-info.yamlに次のような情報を追加します

apiVersion: backstage.io/v1alpha1
kind: API
metadata:
  name: example
  description: Example API
spec:
  type: openapi
  lifecycle: production
  owner: team
  definition:
    $openapi: ./spec/openapi.yaml # by using $openapi Backstage will now resolve all $ref instances

spec.definition.$openapi のところにOpenAPI のYamlファイルパスを指定すればOKです。

上記を指定したCatalog-info.yamlをBackstageに取り込み、Webブラウザで表示すると最初にご覧いただいたような画面が表示されます。

まとめ

今回はBackstageへOpenAPI Catalog pluginを導入する過程とその結果をご紹介させていただきました。

Backstageは様々なPluginを導入することができ、それぞれの開発組織にあったInternal Developer Portal(IDP)を提供できるものです。このように開発チームの負荷を少しでも下げるような環境を作り上げることがPlatform Engineeringの１つの目的だと思います。ただ、Backstageでその自由さを享受しようと思うと、ソースコードの修正が必要になるなど、ちょっと面倒な作業が発生します。私たちはこうした「ちょっと面倒」な部分を少しでもかんたんに実現できるよう、IDPの実現のためのお手伝いをさせて頂いております。ご興味のある方はぜひ、以下の事業部のご紹介のリンクからぜひ音合わせいただければと思います。