これは、Swagger のオープンソースツールとプロフェッショナルプラットフォームである Swaggerhub を使用して、カスタムドキュメントポータルをゼロから構築することに取り組むシリーズの第2部です。
セットアップと初期フレームワークの構築に関する最初の部分をご覧になっていない方は、こちらからご覧いただけます。また、完成したコードのリポジトリはこちらで利用でき、こちらでホストされています。
このシリーズの最初の部分では、ドキュメントポータルを作成する際に使用される環境とツール、およびドキュメントを動的に取得してレンダリングするための初期コンポーネントの構築に焦点を当てました。このベースレイヤーが構築されたので、このポータルを本当に自分たちのものにするためのカスタマイズを検討し始めることができます。
Web開発のあらゆるものと同様に、これを行うには多くの方法があります。理想的には、SwaggerUI コンポーネントに渡すことができるカスタムテンプレートを作成し（現在の「baseLayout」の代わりに）、ページレイアウトとスタイルを本当に変更することです。これは、このシリーズの別の部分で検討されるでしょう。最初のユースケースでは、ドキュメントを「金太郎飴」のように見せないようにするために調整すべき主要なコンポーネントとクラスをいくつか探ります。
セットアップ
デモサイトでは、悪名高い銀河帝国がデジタルトランスフォーメーションを進めていると想定しています。この変革は、銀河全体に旋風を巻き起こし、今後の拡張目標に役立つことを期待されています。大規模な組織内のさまざまなチームやグループが従来のモノリス開発プロセスから離れ、独自の内部サービスを公開し始めるにつれて、これらすべてのドキュメントを1か所でアクセスできるようにし、スタイルの観点からは銀河帝国の全体的なブランドと「雰囲気」と一致させる必要があります。
現在、明るい白の背景に SwaggerUI コンポーネントの基本スタイルを使用しています。これは実用的ですが、組織の全体的なルックアンドフィールとは対照的です。また、ブランドの視覚的な補助として画像やロゴは含まれていません。幸いなことに、作業に役立つカラーパレットが提供されており、組織全体で使用されているフォントライブラリとロゴに頼ることができます。
次のいくつかの手順で、サイトのより暗い配色を迅速に構築し、サイドバーヘッダーを更新して、カスタムフォント、ロゴ、およびサブヘッダーを含めます。前述のとおり、これは理想的な方法ではありませんが、SwaggerUI のデフォルトスタイルと独自の CSS オプションの両方を使用する比較的簡単な方法として、当面は機能します。
ページスタイルの更新
まず検討すべきは、現在のスタイルシートの構造です。前のチュートリアルで構築した内容に基づいて、ページ本文やサイドバーなどの基本コンポーネントの更新を開始できることがわかります。一方、中央の「ドキュメント」ペインは、SwaggerUI コンポーネントの既存の名前と構造に基づいて更新する必要があります。
サイドバーを最終的なビジョンに合わせるために更新してみましょう。これは非常に簡単です。単一のサイドバーボディクラスside-barがあり、リンクは共通のクラス名api-linkを共有しています。現在、これらはすべて同じApp.cssファイルの下にあり、初期設定には問題ありませんでした。
管理しやすくするために、/cssフォルダを作成し、create-react-app で必要なindex.cssを除くすべての CSS ファイルを移動しましょう。アプリケーションが成長するにつれて、コンポーネントと依存関係を整理し、混乱を減らすことが重要です。新しい場所からファイルをロードするために、index.cssに必要な import ステートメントを追加してください。
この機会に、SwaggerUI コンポーネントから読み込んでいる依存スタイルシートも取り込むことができます。/node_modulesフォルダを振り返る（特定のホストサービスを通じてこれがどのように構築されるかによって問題が発生する可能性があります）代わりに、作成したばかりの/cssフォルダにスタイルシートを取り込み、他の必要なファイルと並べておくことができます。このファイルは現在/node_modules/swagger-ui/dist/swagger-ui.cssにあります。または、以下の gist からコピーすることもできます。
ごちゃごちゃしていますが、将来の投稿でゼロからテンプレートを構築することを検討する大きな理由です。今のところ、ヘッダーとドキュメントのスタイルに取り組む前に、side-barのスタイルを調整しましょう。上記のカラーリストからカラーセットがあるので、side-bar.cssファイルを更新できます。
更新は非常にシンプルです。ヘッダーについては次のセクションで説明します。今のところは、
- サイドバーの背景を暗くしました
- 暗い背景に映えるようにテキストの色を反転させました
- サイドバーパネルに新しいフォント
これらの変更のほとんどは、簡単にカスタマイズできるはずです。カスタムフォント（現在および将来使用するもの）については、ブラウザでレンダリングされている最上位の.htmlページにリンクステートメントを追加してください。このプロジェクトで示されているものはGoogle Fontsからのものですが、どのようなものでも機能します。
これで、サイドバーは変更されているはずですが、ページの残りの部分はかなり標準的なままでしょう。ページ本体を更新する前に、サイドバーヘッダーにいくつかのカスタマイズされた要素を追加して、ページの他のスタイルと揃えることができます。
ヘッダーの更新
画像を追加し、サイドバーヘッダーのレイアウトを更新することを知っています。その後、すべてが正しく表示されるようにスタイルシートをいくつか微調整します。ここでは、特にside-bar-headerと、その中のh1要素という、いくつかのクラスに焦点を当てる必要があります。ロゴ画像から始めます。これを残りのファイルと同じ/srcディレクトリに保存することもできますが、これらのファイルを格納するための CMS または画像リポジトリがあると想像してみましょう。これにより、画像が更新された場合でも、アプリケーション側で何も変更する必要がなくなります。以前に作成したorganization_config.jsonファイルにすでにいくつかの情報が保存されていることがわかっており、JSON オブジェクトに現在のデータがあることを確認するだけでよいはずです。
次に、この新しい情報を表示するようにサイドバーコンポーネントを更新する必要があります。Sidebar.jsを開き、サブヘッダーと画像を考慮するように更新します。
JSON オブジェクトを取り込むことで、すでに多くの重労働をこなしています。実際に行う必要があったのは、値がどこかにあるようにすることだけでした。
- imgを追加し、リモートURLを指すようにしました
- h3要素としてサブヘッダーを追加しました
最後に、新しい要素に対応するように CSS ファイルを更新する必要があります。いくつかの最小限の変更で、ページを整理し、必要なコンテキストを与えます。
この時点で、サイドバーはかなり見栄えが良くなっているはずです。スタイルが更新され、ヘッダーセクションに表示される新しい情報がいくつか追加されています。プロセス最後のステップは、SwaggerUI のスタイルを変更して、暗い背景にきれいにレンダリングすることです。
ドキュメントスタイルの更新
最後に、ドキュメントコンポーネント自体に注目できます。現在、おそらくほとんど使用できないように見えます。暗い背景に暗いフォントです。SwaggerUI は、どのスタイルシートをレンダリングするかを選択する際にかなり積極的です。従来であれば、カスタムスタイルをロードし、その後で取り込んだデフォルトのシートをロードでき、CSS の階層が焼き付けられたスタイルよりも変更を上位に浮かせることができたはずです。残念ながら、インポート順序に関係なく、SwaggerUI スタイルが真実として扱われるため、スタイルを更新するには非常に細かく設定する必要があります。
これに取り組む最善の方法は、Chrome デベロッパー ツールの検査ビューのようなものを使用して、不明瞭になっている要素に基づいてクラス名を取得することです。以下のスタイルシートには、以前に実装したダークブルーの背景にきれいにレンダリングされるように更新された、テキストとスタイルのコアセット要素が含まれています。
大まかに言えば、変更は非常に簡単です。
.swagger-ui .infoを使用してすべての情報ブロックを取得し、白い背景を取り入れ、呼吸する余地を与えるためにパディングを追加します。.description pは、説明テキストを白い背景に表示するように更新します。- すべての op-block タグ（OpenAPI 定義のタグ）は白で表示されるように切り替えられました。
- 操作の説明、タイトル、名前などが一つずつ取得され、白で表示されます。
- ページ下部のモデルセクションは、角を四角くし、暗いページの上でより鮮明に表示されるように更新されました。
まとめ
ページをリロードすると、私たちが最初に実装したデザインとは大きく異なり、この場合は組織全体の「外観」とより一致しているはずです。振り返ると、SwaggerUI ライブラリにスタイリングの大部分を処理してもらい、何を更新するかを選択できるのは素晴らしいことですが、すぐに非常に乱雑になる可能性がありました。検査ツールのようなものを使用することで、必要な場所にたどり着くことができましたが、プロジェクトをまったく知らない人には簡単に変更できない、非常に厳密で詳細なソリューションになってしまいました。
幸いなことに、解決策があります！SwaggerUI はカスタムレイアウトの受け渡しを可能にするため、この場合のデフォルトの「BaseLayout」を使用する代わりに、ページ全体を自由に移動し、スタイルを設定し始めることができます。これにより、ページをより簡単にスタイル設定できるだけでなく、画面上のデータの新しい配置（これまで使用してきたカラムビューとは対照的に、Slateなどのライブラリでよく見られるような並列ビューなど）も検討できるようになります。これについては、今後の投稿でゼロから行います。
今のところ、この投稿が、最初に設定した SwaggerUI のデフォルトにカスタムスタイルと情報を重ね始めるための基盤を提供することを願っています。このシリーズの次の投稿では、構築したアプリケーションをいくつかの異なるホストオプション（Netlifyなど）に迅速にデプロイする方法、および環境変数と認証された API 呼び出しを追加して Swaggerhub のプライベート組織にリンクバックする方法について説明します。