BASEプロダクトチームブログ

ネットショップ作成サービス「BASE ( https://thebase.in )」、ショッピングアプリ「BASE ( https://thebase.in/sp )」のプロダクトチームによるブログです。

BASE TemplateとBASE APIのドキュメントをリニューアルしました

f:id:aiyoneda:20190628213529p:plain

はじめに

BASEでは、開発者様向け機能としてBASE Templateと BASE APIを提供しています。 BASE TemplateではBASEショップが使えるHTMLテンプレートの開発を、BASE APIではショップの商品情報や注文などをWEB API経由でアクセスしアプリケーション開発を行うことができます。

今回はその2つの機能のドキュメントサイトをリニューアルしましたのでお知らせ致します。

なぜリニューアルする必要があったのか

以前のドキュメントサイトは、以下のようにGitHub上にドキュメントとしてMarkdownファイルを配置しているだけでした。

template-docs

baseinc/api-docs

機能としては最低限満たしてはおりましたが、デザイン性は乏しく必要な情報へのアクセスも難しいという問題がありました。 加えて、ドキュメントに新しいAPIレスポンスについての情報を加えようとするとGitHubのPull Requestを経由せざるを得ず弊社エンジニアやデザイナー同士の仕様定義についてのやりとりも見えてしまうという問題も存在しておりました。

これらの問題を解決しつつ開発者の皆様に使いやすいドキュメントにリニューアルしていく運びとなりました。

どのようなツールを利用するか

社外向け開発ドキュメントをホストするサービスやツールは数多くあります。 弊社で選定する際に重要視したのは下記です。

  • 既にあるMarkdown ドキュメントを大幅に変更する必要がない
  • ある程度デザインを自由に変更することができる
  • 独自ドメインを割り当てることができる
  • なるべく新しいSaaSなどを利用したくない
  • 検索機能を開発せずに利用できる

もともとドキュメントはmarkdownで書かれていますので、例えばSphinxなどをドキュメントツールとして選定してしまうとrst形式に書き直す必要があります。

今回のリニューアルではドキュメント自体を変更することまでは考えておりませんでしたので作業工数的な考えからも現在のドキュメント資産自体はなるべくそのまま利用できることが重要な条件でした。 検索機能についても同様で、検索機能は必要ではありますが一から開発していくことは望ましくありません。 デザインに関してははBASEのブランドガイドラインに沿ったサイトを構築するのが望ましく、一定のカスタマイズが可能である必要があります。 独自ドメインは大抵のドキュメントツールや静的サイトのホスティングでサポートしています。

ですが、別途SaaSなどを契約することでアカウント管理の煩雑さを増やすことは避けたいという考えもありました。ドキュメントをメンテナンスする社内メンバーは多くいるためそれらの人に改めてアカウント権限を付与する作業が必要となってしまうためです。

Docusaurus + GitHub Pages

上項のような条件のもと、GitBookやHugo、Swagger-UI、API Blueprintなどを試していたところ Docusaurusというツールに出会いました。

https://docusaurus.io/

DocusaurusはFacebook社が公開しているOSS向けReact製のドキュメント作成ツールです。

React NativeやRedux、textlintのようなOSSドキュメントに利用されています。 Docusaurusはmarkdown形式のドキュメントを扱うため、一部の変更は加える必要はありましたがBASEの既存ドキュメントからの移行は問題なくできるようでした。 デザインは柔軟に変更でき、ローカルでの開発も容易でしたのでデザイナー自らがデザイン修正を行うことができました。

Docusaurusでドキュメントを作ることができたのでそれをホストする環境についての選定をしましたが、ここは順当にGitHub Pagesを選定しました。 独自ドメインを扱うことも可能ですし、弊社ではGitHubを元々利用しているため公開フローのために特別なアカウントを必要としないことが選定理由です。 現状問題はほとんどありませんが、ステージング環境のような物が存在しないのでローカルで検証したサイトを複数人で確認し辛い事に少し不安があるなと感じています。

既存ドキュメントの移行作業

ツールの選定が終わったので、あとは既存ドキュメントを移行していきます。

docusaurus のセットアップ

docusaurus-init というツールを利用すると最低限必要な初期ファイルを用意してくれます。 基本的なドキュメント部分は設定ファイルとmarkdownの変更で対応できますが、例えばトップページを変更したい、となった場合はある程度 React の知識が必要になってきます。 リニューアルタイミングで新しい機能が追加される予定だったこともあり、今回はエンジニアがデザインの組み込み込みで構築を担当し、デザイナーを中心にドキュメントの追加、修正、構成の見直しを行いました。

移行作業

既存の markdown のドキュメントからの移行は、ヘッダー情報を付加するのみで行うことができました。 いままではコンテンツのみが書かれていた markdown にこのようなヘッダーを追加します。

---
id: add
title: items/add
---

# POST /1/items/add

商品情報を登録

id は、ドキュメント上で自身が存在するディレクトリを含めたユニークキーとなります。例えばこのファイルは docs/api/items/add.md に配置されているので、実際の id は api/items/add となります。

あとはこれをすべて markdown に追加していき、sidebar.json へ構成を記述すれば完成です。

"docs": {
    "BASE API": [
      "api/index",
      {
        "type": "subcategory",
        "label": "OAuth",
        "ids": [
          "api/oauth/authorize",
          "api/oauth/access_token",
          "api/oauth/refresh_token"
        ]
      },
      {
        "type": "subcategory",
        "label": "Item",
        "ids": [
          "api/items/index",
          "api/items/search",
          "api/items/detail",
          "api/items/add",
          ...

検索

Docusaurusはそのままでは検索を利用する事ができません。 ですが、Docsearchと連携させることで検索機能を使うことができます。 Docsearchはalgolia製の検索を提供してくれているサービスで、OSS向けでは無料で利用することができます。

利用する際はDocsearchのサイトから、利用申請を送る必要があります。 送った後数日で、このサイトの管理者かどうか？といった質問がメールで送られてくるので管理者である旨を返信するとAPI keyなどが送られてきます。 下記のようにconfigが配置されていれば検索が可能になっているのでDocusaurusのsiteconfig.jsonに設定を書き加えることで検索機能が有効になります。

https://github.com/algolia/docsearch-configs/blob/master/configs/thebase.json

検索のレスポンスが驚くほど速いのでDocusaurusを利用しなくとも、Docsearch(algolia)を利用する価値はあると感じました。 docsearch

GitHub Pageへのデプロイ

GitHub PagesへのデプロイはCircleCI 経由でやっています master branchへのcommitを検知すると、デプロイ jobを実行しGitHub Pagesへのデプロイを行っています。 これらの手順もDocsaurusのドキュメントに詳細に書いてあるので手厚いなと感じました。 これによりエンジニアでなくともGitHubのアカウントさえあれば手軽にドキュメントのメンテナンスが行えるようになっています。

ドキュメント上で一部機能の確認が行えるようになりました。

ここからは新機能のお知らせとなりますが、昨今のBASE TemplateはBASE Appの拡充に伴い様々な条件を想定し開発をしていただく必要があります。 しかし、現状のエディタ機能では色々パターンを想定し開発していただくのには不便であることは開発チームとしても課題として受け止めておりました。

そこで、今後のシステムの拡張の先駆けとして、テンプレートのサンドボックス機能を一部実装いたしました。 サンドボックスは BASE Template に関するドキュメントの対応ページで確認することができます。 この機能はテンプレートを作成するにあたって、複雑化するタグの動作イメージをつかんでもらおう、という目的で実装されました。

タグによっては BASE Apps (拡張機能) の有無や、商品に設定されている項目や時間によって動作が異なることがあるため、 動作を確認するためには実際に Apps をインストール、設定、アンインストールしてまたインストールというような労力をかけていただく必要がありました。 サンドボックスではこれを解決するため、Apps の設定を簡略化したものをその場で設定できる機能を搭載しています。

sandbox

この機能は現在一部のタグのみをサポートしていますが、徐々に対応範囲を広げていく予定です。

最後に

今回はBASE TemplateとBASE APIのドキュメントサイトの更新とドキュメントへの機能追加についてお知らせさせていただきました。 開発者の皆様がBASEを使ってHTMLテンプレートやアプリケーション開発をして頂く際の一助としてお使い頂ければと思います。

ご不便な点や間違いなどを見つけられた際には開発チームにメールにてお知らせ頂ければ幸いです。