今晩から東京出張なので運動はおやすみ。縄跳びだけもっていく。

api ドキュメントを継続的に保守することへの考察

お手伝い先のプロダクトを1年半以上、継続している。web api の機能もどんどん増えてきて50は超えていると思う。api ドキュメントをビルドするために redocly cli というツールを使っている。次のスクリプトは .gitlab-ci.yml の設定だけど、このぐらいの手間で openapi.yml から1つの html ドキュメントを生成してくれる。この index.html を api サーバーに同梱している。

  before_script:
    - node --version
    - npm --version
    - npm install @redocly/cli@latest
    - npx redocly --version
  script:
    - |+
      npx redocly build-docs schema/openapi.yml \
        --output index.html \
        --theme.openapi.schemaExpansionLevel=10 \
        --theme.openapi.expandResponses=all \
        --theme.openapi.requiredPropsFirst=true \
        --theme.openapi.jsonSampleExpandLevel=10 \
        --theme.openapi.hideLoading=true \
        --theme.openapi.pathInMiddlePanel=true      
    - mkdir -p public
    - mv index.html public/

web api の機能数が少ないときはこれで十分だった。しかし、50を超えてくると yml で api ドキュメントを保守するのが辛くなってくる。xml/yml/json を問わず、サイズの大きいこれらのファイルを保守するのはつらい。人間の能は複数種別の情報を同時処理できるが、一定量を超えた情報量をうまく処理できない。もちろん機能別にファイル分割して管理しているのだけど、それでも openapi.yml のエンドポイントの定義はどんどん増えていく。それがだんだん辛くなってきたのが現状になる。

以前 静的サイトジェネレーター勉強会の手伝い をしたときに slate という markdown で記述できる api ドキュメントツールがあることを教えてもらった。これはいいなとそのとき思ったのだけど、コミット履歴などをみているともう保守モードで活発に開発されていない。oss あるある話しで継続的に開発されていないツールはすぐに廃れるのでいまから採用するには躊躇してしまう。

postman という api プラットフォームがある。昔から api クライアントとして使う開発者も多かったのでツール自体は知っていた。この機会に私も実際に使ってみて評価した。既存の openapi.yml + redocly cli を使っているドキュメント管理と postman との比較をした。

• postman はドキュメントのバージョン管理ができる
• postman アプリを api ドキュメントのエディターとして使える
  • テキストの説明欄に markdown を記述できる
  • エクスポートすると json データになる
    • ドキュメントのデータとして yml と大きな違いはないが、エディターで隠蔽されるからドキュメントの保守はやりやすくなる
      • 但し、エディターは postman アプリに依存する
• postman はリクエスト CLI とレスポンスの対応関係をセットで管理できる
• ドキュメントの構造や見た目はあまり変わらない

postman そのものは悪くないけど、うちらのいまの開発のワークフローにすぐに適用できる状況でもない。postman の機能を有効に活用できるように開発のやり方を変えないといけない。そうしないと、ドキュメント管理だけに使うには外部サービス依存が大きくて学習コストも高くなってしまう。

別のアプローチとして openapi.yml の編集をテキストファイルで行うのではなく、人間にとって操作しやすいエディター上で行えるようにしたものが stoplight studio になる。ググると評判もよいし、私も実際に使ってみて機能はまさに探していたツールではある。しかし、このツールの先行きも怪しい。これまでデスクトップ版のエディターは無償で提供されていて、いまもアカウント登録すれば無償で使える。しかし、昨年あたりに SmartBear 社 (swagger を作ってた会社ね) に買収されている。おそらく swagger editor の移行先を探していてちょうど都合がよいのだと思う。SmartBear 社は過去の openapi 移行時のゴダゴダがあって印象がよくないし、ビジネス寄りの会社になるので将来的に stoplight studio を無償で使い続けられるかどうかにも懸念がある。

• SmartBear to Acquire Stoplight to Deliver Industry’s Broadest Portfolio of API Development Capabilities

今回は調査したどのツールにも懸念があって採用を見送ることにした。api ドキュメントを書くツールを探すのは難しい。

寝台特急

久しぶりの寝台特急。11時25分頃に乗車券を使って JR 三ノ宮駅の改札を通過しようとするとエラーになった。30日から有効とは書いてあるものの、以前は通過できていた気がしたので駅員さんに聞いたら30分前から通れるはずとの。その後11時38分には改札を通れた。これまで改札でエラーになったことがなかったのは11時30分をまわってからだったんだと初めて気付いた。運が悪いことに0時11分発の予定が32分遅延した。調子の悪いときはこんなもので段取りもうまくいかない。最終的に東京駅には15分ほど遅れになった。

今日は普通のB寝台シングルを予約した。下側の狭い部屋でゆっくり寝ることにした。乗車後10分ほどして車掌さんが切符確認にきた。これもわかっているから扉を開けて切符も用意して待ってた。寝台特急は薄い布団しかついていないから冬はちょっと寒い。逆に夏はエアコンが効いているし薄い布団で問題ない。寝台特急は暖かい時期に乗るのがよさそうだということもわかってきた。

2時前に寝て6時半過ぎに起きた。4時間半も眠れたって感じ。今日も雨降りで外に出れなかった。

今日の運動は腕立てとスクワットをした。統計を 運動の記録 にまとめる。

3次開発の完了

3.5ヶ月を機能開発、QA テストを1ヶ月やって3次開発を完了した。新人の受け入れ失敗、2週間の開発遅れといった失敗もあったが、計画を補正して概ね予定調和で完了することができた。よかったところは最初から一緒にやっているメンバーの成長が大きく、私がプロジェクトを去っても彼らだけでプロジェクトを運営していく見通しをもてるようになってきた。お手伝い先の要望次第だが、次の開発フェーズを終えたら私がマネージャーを務めるのを終えてもよいかもしれない。

開発が無事に完了してよかったねという話しとは別に、3ヶ月前に合流した新しいメンバーへはやや厳しく指導した。QA テストをメンバーみんなで役割分担し、そのメンバーには相対的に簡単なタスクを1ヶ月という期間で与えていたにも関わらず、期日になっても4つある issue のうち、1つも完了させていないという体たらくぶりだった。先週の水曜日に 1on1 して4つのうちの2つだけは必ず完了させてほしいと依頼し、本人も了承していた。もっと言えば、1週間もあれば十分にできる程度のタスクでしかない。にも関わらず、期日に完了していないということに「なぜ出来なかったのか？どうすれば完了できたか？」という議題を提起した。

会議が始まる前にプロジェクトオーナーへも今日は厳し目に指導するからメンバーが落ち込むかもしれないので、そのときはフォローしてくださいと伝えておいた。いまの若い人はストレス耐性がないからちょっと厳しく指摘をすると落ち込むことも推測できた。実際に厳しい指摘をしてみて、私自身も相手がショックを受け過ぎないように言葉を選んだり、できるだけ仕組みをもって改善していくという姿勢で議論を進めた。そういった人間関係の配慮そのものがとても疲れることにも気付いた。昔は上司がボロクソにダメ出しできたのは楽だったんだろうなとも思えた。

リリース作業とインストールテストと手戻り

開発と QA テストを完了したのでコンテナイメージやパッケージをリリースする。実際にインストールテストをやりながらインストールドキュメントも修正していく。これがなかなか大変なことに気付いた。機能が増えたり、仕様が変わったりしたところを1つ1つチェックしていく必要があって、個々の変更は軽微でもそれがいくつも数が多くなると覚えてなくて見逃してしまったりもする。そのことに気付いたら修正は容易だが、インストールテストをやっていて気付いたらパッケージングをやり直すこともいくつか出てくる。新機能追加や仕様変更とドキュメント／パッケージングをつなげるための仕組みがいまない。それも考えていかないといけない。

4時半に寝て7時半に起きた。深夜にハンズオン資料を作っていたらまた眠れなくなった。朝から頭痛くて調子が悪い。きっと生活のリズムが崩れているせい。早くお仕事を終えて帰って寝てた。

今日の筋トレは腕立て:10x1,スクワット15x1をした。

ldap エントリーの更新リクエストをランダムに行うツール

先週末から作っていたテストツールがようやく一通り動くようになった。ldap エントリーを生成したり、既存のエントリーに対して更新、削除、パスワード変更のリクエストをランダムに自動生成して送る。常時 id 連携の処理を動かしたときの並行処理の問題であったり、やや負荷をかけたときになにかの敷居値を超えて不具合がないかといった検証に使える。8月末に開発に着手して、年末から再開して、1月明けでようやく完成した。テストツールの開発の優先度が低いので後回し後回しにしているうちにどんどん後ろに流れていった。悪い開発の典型例。

hugo のハンズオン資料作り

昨日の続き 、、、をやろうと思っていたけど、頭痛でしんどかったので今日はお休み。イベントが公開された。

• 静的サイトジェネレーター勉強会

他のツールをみていて slate というツールは知らなかった。api ドキュメントを書くためのツールとある。

• https://github.com/slatedocs/slate
• https://slatedocs.github.io/slate/

うちはいま redocly というツールを使って openapi のフォーマット (yml) で api ドキュメントを管理している。開発は openapi を使ってなくてドキュメントのためだけに openapi を使っている。量が増えてくると yml でドキュメントを書くのも辛くなってくるので markdown で api ドキュメントを書けるならそれもよいかもしれない。

0時に寝て何度か起きて7時過ぎに起きた。6時に起きようと思ったけど、気付いたら7時になってた。

ドキュメント書き

8月前半にやっていた非機能要件である差分比較の仕組みについてドキュメントを追加した。但し、この機能はまだ品質を保証できないところがあるため experimental という機能にした。そのためのドキュメントとサポートポリシーについても明記した。利用者からのフィードバックを得られることを目的にした開発途中の機能をプロダクトに追加する仕組み化した。あまりエンタープライズ向けの業務システムでそういった機能を多用するようなことはないと思うけど、QA を十分にできなくてまだ品質に自信がないといったときにも使えるかもしれない。

実務スタッフの訪問

先日の 暑さ対策委員会 の続き。

そろそろ電話しようかと考えていたところ、スタッフが訪問してくれた。7月の中旬からクレームを上げていて、初めてオフィスに来てくれて室温が高いことを確認してくれた。いまだと昼間は30℃ぐらい。その人は過去の経緯をわかっていないようで、フィルター交換と冷媒交換をしたが、まったく効果がないことを丁寧に説明し、エアコンのコントロールパネルの温度・風量設定もまったく機能しないことを伝えた。明日の午前中に工事の業者と一緒に調査してくれるという。ようやく人が来てちゃんと確認してくれた。明日の作業に期待。

クレジットカードの明細のリアルタイム連携

先週末の小旅行にかかった経費の領収書を会計システムに登録した。30分もあればできるのにずっと後回しにしていた。

唐突だが、freeeカード Unlimited がすごくよい。起業時に作った法人向けのクレジットカードは所持しているが、クレジットカードの盗難・紛失時の冗長化の目的で4月に携帯用のカードとして導入した。これが後発のせいか、freee のシステムとの親和性を考慮しているのか、まだ使っているユーザーが少ないからなのか、ほぼリアルタイムで決済情報が会計システムに連携される。

もともと使っていた旧来のクレジットカードと比較できるため、会計システムと決済情報のデータが迅速 (ほぼリアルタイム) に連携すると、実際に運用してみて事務手続き工数を削減できることに気付いた。旧来のクレジットカードは決済情報を取得するのに2週間ほどかかり、さらに先方のシステムの都合で月の負荷が高くなりそうな期間 (10-14日とか) は連携不可といった運用になっている。2週間経ってから決済情報をみても何にお金を使ったのか思い出すのに少し時間がかかったり、請求書などを調べて確認したりする作業が発生する。クレジットカードで支払った直後に会計システムに取引登録するのがもっとも事務手続き工数を削減できることに気付いた。

半年間ほど新旧のクレジットカードで運用してみて、旧来のクレジットカードによる決済を置き換えていくことに決めた。今後は Unlimited なクレジットカードを2つ使って冗長化した運用にしようと思う。

速さは正義。

1時に寝て何度か起きて6時半に起きた。気分転換も兼ねた非日常の小旅行を終えてまた元の生活へ戻していく。

ドキュメント書き

昨日の続き。ドキュメントの一部レビューをお願いしているところがあるので別のところのドキュメントを書いていた。その過程で ldap の anonymous bind の設定ができないような制御になっていることに気付いてその設定を修正したりした。ドキュメントを書いていてバグをみつけた。

近況報告の資料作り

四国から帰ってきたばかりなのに来週は東京へ行かないといけない。開発はほぼ完了しているのでなにも憂いはないが、出張のタイミングで大きなふりかえりや次の開発フェーズの要件の発散などもやりたい。そのための資料の準備がまったくできていないことに昨日の夜、気付いた。明日・明後日ぐらいで準備して、できるだけ事前に参加者に共有したい。いまは忙しくないのだけど、なぜか空き時間をうまく作れなくても毎日バタバタしている感がある。

今日は月例の近況報告の資料を作っていた。客観的に、このタイミングで私を契約終了としてもよいだろうし、私の感覚的には次の開発フェーズを3-4ヶ月みて、その後にチームのメンバーにこのプロダクト開発を委譲するといった段取りがよいのではないかと考えている。そういった話しも来週はしてくるつもり。長く残ったとしても今年度いっぱいが区切りとしてよいのではないかな。

実家へ帰って疲れていたせいか、21時過ぎから寝てしまって2-3時間ごとに起きて5時半に起きた。親はもっと早くから起きているからその時間から朝ご飯が出てくる。

ドキュメント書き

持ち帰ったばかりの机とバランスチェア を使って初めてのリモートワーク。とくに問題なく作業できたのでよさそうに思う。今日は早くお仕事を切り上げるために7時からお仕事を始めた。issue の対応を見守りながらドキュメントをまとめて書いていた。新規追加した機能やまったく違う仕組みに置き換えたものがあるため、ドキュメントの変更量が多い。

お昼にメンバーからも qa テストの完了報告が届いて、私も自分がもっている issue ではバグ修正もすべて終えていて、あとはドキュメントと最後の GA 向けのパッケージングぐらい。いつもそう思うけれど、終わってみれば順調に予定通り開発のイテレーションを完了できた。今回は機能開発に約3ヶ月、QA に1ヶ月の約4ヶ月のイテレーションとなった。開発の状況をみながらマイルストーン (2週間) を増やしたりもした。その程度の調整もした上で予定通りと言える。3ヶ月のイテレーションに対して、私がマネジメントをしていれば前後2週間程度のズレしか出ない。こんなの当たり前だと思うが、以前お手伝いしたスクラム開発でのストーリポイントでは2ヶ月の見積もりに対して4ヶ月を要した。見積もりがめちゃくちゃだったと言える。

帰路に着く

てらださんが鳴門から淡路島南 IC に15時30分に着くという予定を教えてもらっていた。そのため、15時にお仕事を切り上げて、迎えに行って、それから神戸に一緒に帰ってきた。

たこせんべいの種類

帰路の途中で たこせんべいの里 へ立ち寄った。津名一宮 IC のすぐ近くにある。おそらく私は行ったことなかったと思う。長居するような観光施設ではないが、立ち寄ってみたらそれなりにおもしろかった。てらださんの奥さんがたこせんべい好きらしくて、いろいろ教えてくれた。50種類ぐらいある。たこせんべいっていろいろ入っていることは知っていたけど、こんなに多くの種類があるとは知らなかった。たこせんべいの個別試食ができて、コーヒーも飲めて、工場見学して、お土産にせんべい買って帰った。16時半には出発した。

新神戸駅

快調に高速道路を走って、3号神戸線を迂回して7号北神戸線から神戸へ戻る。道中で若宮-芦屋間で渋滞18kmとか出ていた。いつものこと。てらださんに 3号神戸線のうんちく をたくさん語って満足。この日のためのネタだ。17時には新神戸駅に到着して送り届けられた。無事に旅程をこなせてよかったと私がほっとした。

小旅行の所感

てらださんがオープンセミナー参加のために香川県へ来られるという話しを聞いて、車も買ったばかりだし地元だから案内しようと考えた。その延長で LT 発表しようと思いつき、ある記事を翻訳したらちょっとバズって世の中の役に立ったのかもしれない。

私はなにも用事がなければ出掛けないことが多い。いまは基本的にずっと会社のお仕事をしているし、そんな毎日でも不満もない。だからこそ、なおさらこういった縁の機会が大事だとわかるようになってきた。てらださんが来られなければ、この3泊4日の小旅行はあり得なかった。そして 車中泊の経験 も得られなかった。新しいことを学ぶ機会そのものが尊い。旅程を通して関わってくれた周りの人たちに感謝したい。

これは昔はらさんからも助言をいただいたことを覚えている。私が交際費を年間で2-3万円しか使っていなかったときのこと。

放っておいて会社にお仕事が舞い込んだりしない。
いまのお仕事がずっと続くことはあり得ない。
将来のために新しい縁を自分から探しに行かない限り、会社を継続できない。

2時に寝て何度か起きて7時に起きた。今日は勉強会の登板なのになにも準備できてなくてどうしようとか思いながら寝た。

パッケージングとリリースのドキュメント

5月の落ち穂拾いの時期にプロジェクトの開発ドキュメントを刷新していろいろな要項を書き残している。最後に残ったまだ書いていないドキュメントに次の2つがある。水曜日から課題管理やコードレビューの隙間時間に書き出していって3日ほどかけて一通り書き終えた。私は文章を書くのが遅いのと、1回ですべての内容を網羅できなくて、書いているうちに思い出して追記したり、寝かした文章をあとで見返して推敲したりすることが多い。そのため、ドキュメントを1週間ぐらいかけて書いたりする。

• パッケージング
• リリース

たまたまメンバーにあるモジュールをリファクタリングのために再実装してもらっている。その開発を完了したら古いモジュールと入れ替える必要があるので、開発だけではなく、パッケージングやリリース周りの作業を把握してもらう、よい機会と言える。これまでパッケージングやリリース周りのインフラはほとんど私が作って運用をまわしてきたので徐々にそれらを引き継ぐタイミングとも言える。開発者はインフラのことを気にせず、アプリケーションを開発してコミットすれば後はすべて ci/cd が自動的にいろいろやってくれて便利ぐらいの感覚で扱えるようにするのが、外資系などではプラットフォームに投資しろと言われたりするものだと推測する。うちらが開発しているプロダクトはコンテナ、RPM、Windows インストーラーとパッケージングする種類が多い。その要項に加えて QA 責任の考え方などについても書いておいた。主には私がいなくなった後に役に立つドキュメントとなるだろう。

チーム勉強会

本当は go の generics の勉強会をやりますと先週宣言していた。しかし、私が遊んでいて全然準備できなかったので代わりに決済とスマートプラグの話しをした。先週末と月曜日 に作った決済とスマートプラグを組み合わせたもの。サービスや仕組みを簡単に説明して、実際にデモを動かして電球を灯す。

参加者からスマートプラグをラズベリーパイに置き換えてパワーリレーというモジュールを使えばもっとスマートにできるんじゃないかという意見が出た。たしかにラズベリーパイなら stripe の決済イベントを受け取るサーバーをデバイス内に同梱させることもできるかもしれない。そうすると、スマートプラグのような電源の on/off だけではなく、ラズベリーパイが扱えるセンサーとインテグレーションすることもできそう。また時間のあるときにやってみたい。コラボレーションって正にこういうことを言うとわかってきた。私が1人でこの仕組みを実装していたときにはラズベリーパイというキーワードはまったく頭の中になかった。他者の視点が加わるから新しいアイディアが広がる。

一昨日あまり寝てなかったので昨日は早く帰ってきて20時から22時ぐらいまで寝て、その後0時ぐらいから寝て何度か起きて7時に起きた。久しぶりによく寝た。

プロダクトのドキュメント

プロダクトのインストールや設定のドキュメントを mdBook で書いている。チームのメンバーが reStructuredText を知らないというので markdown で書ける方がいいかと思って採用した。4月上旬から環境作り して時間のあるときに少しずつ書き足したり、メンバーにも書いてもらうように促したりしていた。情報としてはだいたい半分ぐらい書けたかなぁといったところ。まだまだ内容は足りていない。

内容とは別に、ある程度まとまったドキュメントとしてのわかりやすさを、例えば Sphinx のようなツールと比較してどうかというのを書き終えたら比較してみようと思う。1つ懸念点としてわかったことに SUMMARY.md からリンクされていない md ファイルはレンダリングされないという仕様になっていて、この仕様の是非や目次の作り方の構成に制約が課せられることへの懸念がある。次の issue でも議論されている。

• It is recommended that all md files in the directory be converted to html #830
• Files not in SUMMARY.md are not parsed #702

mdbook は私が想定したほど普通のドキュメントツールが備えているような機能を実装していなくて、それは markdown を独自拡張したくないという意志なのかもしれないけれど、本当に最低限の体裁だけでドキュメントのようにみえるようにするといったところしか関心がないのかもしれない。ちょっと触った雰囲気でも本格的なドキュメントを書くツールではないと感じている。私がまだわかっていないだけかもしれないのでもうちょっと触ってみてまた所感をまとめる。

チーム勉強会

2週間ぶりのチーム勉強会。メンバーが Stable Diffusion の話しをしてくれた。学生時代に関連する研究をしていたらしい。本人は研究していたから内容を理解しているのだろうけど、一般人の私には全然ついていけなくて説明そのものが難しいなと思いながら聞いていた。そして、最近の研究成果などを紹介しながら15分ぐらいで終わった。論文の内容を理解できているのなら、その内容を解説してもよかったのでは？と思ったりもした。1時間の枠があるのだからもっと話してもらってよかったのだけど、準備も大変だったのかもしれない。時間が余っていたので私がモデレーターとして質問したり、他の参加者に質問を促したりしながら残り時間の40分ほど雑談していた。そういう意味では雑談会としては多くの質問やコメントが出てよかったと思う。意図的に発表時間を短くして雑談会にもっていくというやり方もあるのかな？と勉強会の運営の学びにもなった。

出張する日は寝ないで資料を作ったりバグ修正したりして始発の新幹線の中で寝てた。寝てなくて疲れているせいか、新幹線で寝るのに慣れたのか、わりと2-3時間ぐっすり新幹線で眠れるようになってきた。普通にベッドで寝ても3時間ぐらいしか眠れないので睡眠時間はあまり変わらない。

docker registry の構築

先日の調査 の続き。Deploy a registry server に書いてあることを実際にローカルで検証した。

tls の自己証明書の作成。subjectAltName という設定をするように書いてある。

$ openssl req -newkey rsa:4096 -nodes -sha256 -keyout certs/domain.key -addext "subjectAltName = DNS:myhost.mydomain.example.com" -x509 -days 365 -out certs/domain.crt

basic 認証のための htpasswd の設定。htpasswd とか懐かしいなと思いながら実行した。

$ docker run --entrypoint htpasswd httpd:2 -Bbn user1 secret1 >> dot_htpasswd
$ docker run --entrypoint htpasswd httpd:2 -Bbn user2 secret2 >> dot_htpasswd

docker 社が提供する oss な docker registry サーバーを使って起動する。

$ mkdir /mnt/registry  # docker image を永続化する場所
$ sudo docker run -d \
  --restart=always \
  --name registry \
  -v "$(pwd)"/auth:/auth \
  -e "REGISTRY_AUTH=htpasswd" \
  -e "REGISTRY_AUTH_HTPASSWD_REALM=Registry Realm" \
  -e "REGISTRY_AUTH_HTPASSWD_PATH=/auth/dot_htpasswd" \
  -v "$(pwd)"/certs:/certs \
  -e "REGISTRY_HTTP_ADDR=0.0.0.0:443" \
  -e "REGISTRY_HTTP_TLS_CERTIFICATE=/certs/domain.crt" \
  -e "REGISTRY_HTTP_TLS_KEY=/certs/domain.key" \
  -p 8443:443 \
  -v /mnt/registry:/var/lib/registry \
  registry:2

これで basic 認証付きで https で通信できる docker registry サーバーができた。

外部のマシンから dokcer login しようとすると次のようなエラーが発生する。

$ docker login myhost.mydomain.example.com:8443
Username: user2
Password: ***
Error response from daemon: Get "https://myhost.mydomain.example.com:8443/v2/": x509: certificate signed by unknown authority

Test an insecure registry によると、自己証明書を使って外部からアクセスできるようにするためには docker client 側にさっき作った domain.crt をコピーする必要がある。

linux だとこんな設定。

$ cp domain.crt /etc/docker/certs.d/myhost.mydomain.example.com:8443/ca.crt 

Docker Desktop for Mac を使っている場合はこんな感じ。

> security add-trusted-cert -d -r trustRoot -k ~/Library/Keychains/login.keychain path/to/certs/domain.crt

これで外部からも docker login して任意の docker image を push/pull できるようになる。docker registry サーバーは Let’s Encrypt をサポートしているそうなので How It Works を参照して設定すればよいと書いてあった。

mdbook の初期設定

mdbook は新しい rust のバージョンだとビルドできなかったりするので rustup を使ってローカルに rustc をインストールするのがよいかもしれない。プラグインとしては mdbook-mermaid を使う。

$ curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
$ ~/.cargo/bin/rustc --version
$ cargo install mdbook mdbook-mermaid

mdbook-mermaid の設定も簡単でドキュメントルート配下に mermaid の js ファイルを配置すると動いた。

$ vi book.toml
[preprocessor.mermaid]
command = "mdbook-mermaid"

[output.html]
additional-js = ["mermaid.min.js", "mermaid-init.js"]

23時に寝て2時頃に少し吐いて起きた。夜遅めに日本酒飲んでいい気分で寝たものの、もう夜に食べたらダメな体になりつつある。4時ぐらいまで起きててそれから寝て7時に起きた。

echo の静的ファイルの扱い

web api のドキュメントは openapi スキーマを使って生成 している。本当はこのドキュメントを gitlab pages で公開させたいのだけど、まだそのインフラ構築ができていなくて先送りになっている。いつもローカルで gitlab ci/cd がビルドしたドキュメントをみていたのだけど、ある機能開発をするときにローカルで web api ドキュメントみるの飽きたなと思って、web api サーバーに同梱してしまえと思い立った。テスト環境の web api サーバーは常に動いているのだから、そこに web api のドキュメントが同梱されていて、なんの不都合があろうか？ (いや、なにもない) 。

次のドキュメントに echo で静的ファイルを扱う方法が書いてある。

• Static Files

ミドルウェアで実装されているようで簡単に静的ファイルを返せる。指定したパスのディレクトリ配下を扱えるのが Static で、指定したパスのファイルを扱うのが File になる。web api ドキュメントのようなものならキャッシュしてもいいなとは思ったものの、次の issue によると v4 ではミドルウェアで自前実装しないといけないらしい。v5 ではその仕組みが echo の機能として入るかもしれない。

• TTL (Cache-Control header in response) for static files #1902

その後、gitlab ci/cd で web api サーバーのビルド後、openapi.yml からドキュメント生成をして、任意の static ディレクトリに配置するように設定した。docker のマルチステージビルドを使うと簡単にできる。バックエンドやっていて、サーバーとインフラの両方に手を入れて機能を作っていくときの、うまくできると利便性と達成感の両方を得られるのが楽しい。web api サーバーがドキュメントを提供することは、要件に含まれるわけでも、誰かに指示されたわけでもない。私が勝手にローカルでドキュメントみるの飽きたと思って、勝手に作って、勝手に動くようにしただけ。こういう開発の遊びのゆとりや権限をチームのメンバーにも与えられるようにしていきたい。開発が楽しくて悪いことはなにもないと思うんよね。

23時に寝て6時半に起きた。前日飲み歩いてホテル着いたら酔いつぶれてバタンキューで寝てた。コロナ禍で飲み歩くことがなくなってたのでこういう寝方もすごく久しぶり。

ドーミーイン池袋

自費で泊まる宿泊先を選ぶときにふと 大浴場 があるところにしようと思った。昔は大浴場があって部屋のお風呂がないホテルの方が宿泊料金が安い傾向があったからよく泊まっていた。最近はそういうホテルが淘汰されて、カプセルホテルに近いものと大浴場がセットになって、普通のホテルは大浴場があるところが減ってしまった。あってもそれを付加価値として通常よりも料金が高めになっているようにみえる。大浴場があって宿泊料金が高くない候補の1つにドーミーインがある。予約が空いていたのが池袋だった。

せっかく大きいお風呂に入ろうと予約したので朝起きてから入ってきた。早朝なので空いててほぼ貸し切りのように広いお風呂に浸かれて快適だった。お風呂を出た隣には漫画スペースもあって時間があれば漫画でも読みたい気分になった。部屋に戻ってきて荷物を整理して出掛けようとしたときにおもてなしがあることに気付いた。冷蔵庫をあけたらプリンがあって、ちょっと固いプリンだったけれど、おもてなしの配慮が嬉しくてよかったと思う。ドーミーインはコストパフォーマンスに優れていて設備も配慮も行き届いていてよいホテルだなと改めて感心した。

製品カタログのたたき台作り

合間にコードレビューなどをやりながら、製品カタログの資料作りをしていた。作業を進めているうちに、私は顧客のことを知らなさ過ぎるのでどういった内容が顧客に訴求できるのかわからないことに気付いた。そこで作業の目的を変更して、製品カタログの叩き台を作ることにした。この資料から顧客のことをわかっている人が訴求点を改善してさらに洗練させてほしいという意図で作った。叩き台の叩き台の時点で公開して、メンバーにレビューもしてもらいながら指摘事項を直したりしていた。後日、プロジェクトの進捗報告とともに経営者に説明する。