25000行超えのAPIドキュメントを分割した話
はじめに COUNTERWORKSバックエンドエンジニアの伊藤です。 この記事ではAPIドキュメント分割の知見を紹介します。 弊社では OpenAPI を使用したスキーマ駆動開発を採用しています。 1ファイルで管理していたところ、25000行を超える行数となり管理コストが高くなっていました。 そこで分割作業を実施したのですが、どのような方針でどう対応したかを紹介します。 1ファイルで運用するデメリット そもそもどんなデメリットが発生していたのかを記載します。 全体の構造が把握しづらく、新規参画者への認知負荷が高い 行数が多すぎるため、RubyMine など IDE やエディタのパフォーマンスが落ちる 1ファイルの内部で複数の箇所を参照しているが、それぞれCommand fで該当部分を探す必要がある。そのため、見ているコードの箇所が頻繁に飛んで情報が追いづらい 実際にやったこと 方針 チーム
zod-to-openapiで、既存のAPI実装にOpenAPIドキュメントを後付けする | Memory ice cubes
昔々あるところに、既存のWeb APIの実装がありました。 それなりに実装を進めた後に、天の声が言いました。「OpenAPIのドキュメントを公開したい」と。 さて、あなたならどうする？っていうニッチな問いに対する一つの答えとして。 ルーターごと乗り換える？ たとえば今回でいうと、元のAPIはCloudflare Workersにデプロイされてた。 ので、たとえばhonoとかitty-routerとか、OpenAPIのドキュメント生成ができるエコシステムが整ってるルーターに乗り換えてしまうという手がある。 https://github.com/honojs/middleware/tree/main/packages/zod-openapi hono好きなあなたに https://github.com/cloudflare/itty-router-openapi/ itty-router好きな
swaggerでAPIドキュメントを書いたらめっちゃはかどった話 - kaz29
Swaggerは、REST APIの仕様とそれに関連するツール群の総称です。REST APIの仕様を定義したJSONファイル(Swagger Spec)を軸に以下のようなツールから構成されています。 Swagger UI - Swagger Spec から動的にAPIドキュメントを生成するツール Swagger Editor - Swagger Specのエディタ Swagger Codegen - Swagger Specからクライアントのコードを生成するツール 最近では、Open API InitiativeがAPIの記述のためにSwaggerを採用して話題になりました。 www.publickey1.jp APIドキュメントのメンテは結構面倒 一般的にAPIの仕様書は、古くはExcel/Wordなどを使ったり、最近ではWikiやMarkdown形式で記述したりなどプロジェクトによって
僕が考えた最強のAPIドキュメント生成 - 銀の人のメモ帳
2023 追記 2023 年現在では、以下の文章では採用を見送っている OpenAPI を使えば OK という雰囲気です。 Web APIの設計 作者:Arnaud Lauret翔泳社Amazon TL; DR ドキュメント生成にはkevinrenskers/raml2htmlを使った ドキュメントはRAML - RESTful API modeling languageで書いた RAMLにはJSON SchemaとJSONを記載できる APIで返ってくるJSONはRailsアプリのrequest specでJSON Schemaを使ってテストした JSON Schemaはr7kamura/json_worldで生成した ドキュメントに載せる例示のJSONもJSON Schemaからgin0606/screijiを使って生成した 上記の方法だとリクエストパラメタとドキュメントの整合性を担保
Springfox+Swagger+Bootprintによる即席REST API仕様書作成 - Taste of Tech Topics
こんにちは。阪本です。 世の中、Swaggerが注目を浴びてきていますね。 開発のスピードアップが求められる中、「外部IF仕様書なんて書いてられねぇ！！」なんて言って実装をバリバリ進めてしまいそうですが（アカンアカン）、そうは言っても外部IF、他社との仕様調整も必要。 そんなときに有効な、実装しながら仕様書も作れるSpringfox+Swaggerに加え、ドキュメント生成ツールのBootprintを使って、簡易的な仕様書を作ってみました。 仕様書の動的生成 以下のようなシンプルなSpringBootアプリケーションから、REST APIを生成してみます。 @SpringBootApplication public class SwaggerExampleMain { public static void main(String[] args) { SpringApplication.run
REST APIドキュメント生成パターン - ✘╹◡╹✘
REST API用のドキュメントを生成するときにどうやってるかについて雑記を残しとく。 概要 実装とドキュメントの乖離を避けるためには、同じ意味情報を二箇所以上に定義することを避ける必要がある。そのための方法として、実装それ自身か、もしくは実装が参照している何らかのメタデータを元にしてドキュメントを生成したり、テストの実行結果からドキュメントを生成するというパターンがある。 テストから Cookpadでは、autodocというライブラリを利用して、RSpecでテストを実行している途中で得られたメタデータからドキュメントを生成している。これはテストの実行結果からドキュメントを生成するパターン。 これは実現方法としてはかなり特殊な部類。このパターンが最も効果的に働くのは、ドキュメント生成のために余分な開発コストはあまり掛けたくないが、テストは真面目に書いている OR 真面目に書いてほしい、とい
Javadoc の書き方 - イトウ アスカ blog
みなさん、Javadoc 書いてますか？ Javadoc は「API ドキュメント」と言われることが多いように、主にライブラリ的なプログラムで書いてこそのものだと思っている方もいるかもしれません。しかしながら、仕様書を Word や Excel（笑）で別途作ると、プログラムと仕様書の同期がとれてないというはめに陥り易くなりますので、Javadoc はどんなときも活用したいというのが私の考え方です。 まず、overview.html を書け Javadoc コメントをいくらか書くような人でも、overview.html を書く人は意外と少ないのではないでしょうか。リファクタリングが何度となく行われるアジャイル開発の現場では、クラスの構成がよくかわりますので、いちいち詳しいコメントを書いていられないということはあるかもしれませんが、overview.html はそれほど何度も手をつけるようなも
1
リリース、障害情報などのサービスのお知らせ
最新の人気エントリーの配信
j次のブックマーク
k前のブックマーク
lあとで読む
eコメント一覧を開く
oページを開く
こんなに使える！今どきのAPIドキュメンテーションツール