DeepSeekのAPI Documentがすごく良い

DeepSeekが話題になっていたので、どんなもんかと思ってAPI Docを見た。

すごく...良い。筆者はOSSを作成する都合上、OpenAPI, Anthropic Claude, Gemini, GrokなどのAPI Docをそれなりに読み込んできたが、DeepSeekのAPI Docはこれまで見た中でぶっちぎりに素晴らしいと感じた。以下に良いと感じたポイントを述べていく。

Request / Response Schemaが明確にわかる

一つのRequestで送信されるJSONのSchemaがツリー状に表示されている。プロパティ間の関係も分かりやすいし、最大値、最小値、デフォルト値なども表記されているので、どのような値が想定されているのか一目で理解することができる。

これらの情報はOpenAPIに準拠したSchemaから生成されていると思われるが、特に好ましいと感じたのは messages などのように複数のEntityが想定されているプロパティについても oneOf を利用して表現されていることだ。

LLMのAPIを利用する場合、 messages にさまざまな型のJSONが詰め込まれる。取りうる型を列挙して見せてくれるSchemaの表現は他の類似サービスが提供するAPI Docでは見られなかった良い点である。

その場でAPIリクエストを送信して結果を確認することができる

Request / Response Schemaをツリー状に表現する方法は、例えばredocというツールでも実現できるようだ。

筆者は業務で主にswagger uiを利用しているが、swagger uiはredocよりもschemaの一覧性が低い反面、その場でAPIを叩いてresponseを確認することができるというメリットがあった。

DeepSeekのAPI DocではAPIを叩いてresponseを確認するUIも同時に提供されている。

デフォルトのJSONが最初からセットされている点もありがたく、適当に値を編集して結果を確認することができた。

補足

DeepSeekのAPI Docを褒めちぎってきたが、GeminiやGrokなどの後発の（Geminiが後発かどうかは疑問だが）APIに貧相なドキュメントしか用意されていないのは、それなりの理由がある。

これら後発のAPIの多くはOpenAI API互換なAPIを実装しているのである。例えばGeminiには OpenAIの互換性 というページがあるし、Grokは OpenAI APIないしAnthropic Claude APIに互換性がある と解説している。

OpenAI APIに準拠しているのだから詳しい内容はそちらのページを参照してくれ、というのはメンテナンスの手間を考えると、それなりに合理性のある態度なのではないかと思う。

ちなみにDeepSeek APIもOpenAI API互換である。にもかかわらずDeepSeekがこれだけのAPI Docを出してきたというのは、顧客も開発者もガッツリ囲い込んでいくぞという意思表示のようにも感じられた。

このAPI Docはいったい何なのか

このAPI Doc自体が何なのか、DeepSeekのGitHub orgから推測することはできなかった。しかし、DeepSeekのAPI Docに表示されるサムネイルからDocusaurusを何かしらカスタマイズしたものであることは間違いなさそうだ。

簡単に検索したところ、 Docusaurusu-openapi が最も近しいようだった。すでに利用している方がいれば使い勝手や良い点 / 不満な点についてコメントをもらえると嬉しい。