documentation - Slate vs Swagger - どちらが優れていて、どちらがより多くのオプションを持っていますか?

Question

API を文書化する必要があります。SlateまたはSwaggerのいずれかを使用する必要があります。どちらがより多くのオプション、長所と短所を持っているか、どちらが優れているかを知りたいです。

Answer 1

Swagger と Slate は、2 つの異なる目的を果たします。Swagger は、RESTful API を記述する標準化された方法の試みです (たとえば、ApiBlueprintに似ています) 。

Swagger は、REST API の記述を可能にする JSON ベースの API 定義形式です。

~ Swagger の API 設計ツール

一方、スレートは、優れた API ドキュメントを作成するための美しいテーマです。

1. 2つは相互に排他的ではありません
2. 理想的には、Swagger API の説明からスレート ドキュメントを生成する必要があります。

Swagger の目標は、他のユーザーが広範なツール (ドキュメント、API エクスプローラー、モック サーバー、コード生成、テスト ユーティリティなど) を構築できる標準を提供することです。例を参照してください: Swagger ツール

あなたの質問への詳細：swagger用のスレートツール：

• これはスレートをテーマにした闊歩UIへのリンクです
• これは、 Swagger 定義に基づいてスレート ドキュメントを生成するプロジェクトです。

したがって、この 2 つは相互に排他的ではありませんが、あなたの直接の質問に対して: Swagger を実装すると、より多くのオプションと柔軟性が得られます (また、スレート ドキュメントを生成する機能もありました)。

Answer 2

私の見解では、これらのツールには非常に異なる目的があります。Swagger は記述言語ですが、スレートは単なるドキュメント用です。

私は Swagger を使用して記述を作成しました。そこから、API のさまざまなクライアントを自動生成したり、ドキュメントを自動生成したりできます。

また、swagger 仕様から Markdown を作成し、それらの Markdown を Slate で使用することもできます。[1]

[1] https://github.com/RobWin/swagger2markup

Answer 3

python-flaskをベースにslate-flask( https://github.com/AhnSeongHyun/slate-flask )を作っています。

特徴：

• 構成ファイル(config.json) : JSON 形式に基づいて config.json を使用して、サンプル コードのタイトル、プログラミング言語を設定します。また、API ドキュメントのパスと TOC (目次) を設定します。

• マルチ API ドキュメントのサポート: 元のスレートは、Markdown 形式に基づく 1 つの API ドキュメントをサポートします。しかし、slate-flask は TOC(index.json) を使用して効率的な管理とドキュメントの量のためにマルチ API ドキュメントをサポートします。

• ドキュメントの動的変更に対応 : サーバーを再起動することなく、API ドキュメントの変更を反映できます。Web ページの更新時に変更があった場合、slate-flask は API ドキュメントをリロードします。ユーザーは API ドキュメントの作成のみに集中します。