# Szpp-judge バックエンドの API ドキュメントをどうするか 2023-01-21 --- ↑について考え、調査してみた記録 :::info 雑です。 ドキュメント一般について書いてあるようなタイトルですが、OpenAPI についてしか考えていません。 OpenAPI 周りのツールを選ぶ際には対応している OpenAPI 仕様のバージョンが2なのか3なのかをよく確認しましょう。ばーじょんってなんのこと？って方は **[この記事](https://future-architect.github.io/articles/20220622b/)** が参考になります。 ::: ## 大まかに3通りの方向性 - A 人力で作る(現状) - B ソースコードからドキュメントを生成する - C ドキュメントからコードを生成する 人力でソースコードとドキュメントの同期を取るか、コード駆動か、スキーマ駆動か。 | | A | B | C | | ----- | :--- | :--- | :--- | | 特徴とメリット | ある程度サーバのコードが出来上がっていることもあり、今から導入するとなるとなんだかんだこれがベストな気もする。 | 今からバックエンドのソースコードに手を加える、あるいはディレクトリ構成を大きく変えるような作業をする手間が比較的少ないことが予想されるのでその点は良さそう。Python の FastAPI だとコードを書くと勝手に OpenAPI 形式のドキュメントが作られるので、そのへんフレームワークががっちりやってればできると思う。 |OpenAPI を唯一絶対の情報源にすることができるのでコードとドキュメントの乖離が起きない。ドキュメント書く→コードを生成するコマンドを実行→ガワだけできるので中身を実装、の流れを繰り返す開発フローになる。| | デメリット | もちろんソースコードとドキュメントの内容が乖離することが容易に想像できるのでそことのバランスやな。| できるとは書いたが FastAPI のような例は稀有かも。ソースコードのコメントに **OpenAPI もどきのコメント** を書いておくとそこから OpenAPI 形式に変換してくれる程度のものが多いっぽい。OpenAPI の書き方を覚えるだけでもダルいのにコメントの書き方も覚えるのって二度手間では。できればコメントではなく入出力の型から自動生成するぐらいのことはしてほしい。|ゼロから作る、開発方針を設計する段階ならまだしも途中から導入するのって難しそう[要検証]| | 関連ツール | [swagger-editor](https://github.com/swagger-api/swagger-editor/blob/master/README.md#docker) (docker があればブラウザでエディタが起動するので便利) |actix-web でも使えるものでいうと [utopia](https://github.com/juhaku/utoipa) とか [paperclip](https://github.com/paperclip-rs/paperclip)|[openapi-generator](https://github.com/OpenAPITools/openapi-generator)など多数| C について補足。スキーマ駆動のやり方は上に書いた「ドキュメントを自力で書く→コード自動生成」以外にも「中間言語(DSL)を自力で書く→ドキュメント＆コード自動生成」という方法もある。golangだが例えば **[こういう例](https://logmi.jp/tech/articles/323091)** がある。 ## その他参考資料 - [OpenAPIによるRustのコード生成](https://note.com/takahashiki/n/na87a6fe33df1) おわり