ついに、書類を書くのに苦労する必要がなくなりました。デバッグ可能な API ドキュメントを生成する方法を教える

私はいつも書類を書かなければなりません。書かないとコードを維持できないので、書かなければなりません。でも、文書を書くのは時間も労力もかかる、そしてさらに恐ろしいのは、書いた後も非常に読みにくい本棚にしまっておく、いつも時間が無駄だと感じています、それは本当に悲惨。

私はいつも「文書を書く」ことに悩まされてきましたが、偶然神々しい記事を読んで、インターネットで自動化ツールとDSLの理論を調べたところ、突然の啓蒙がありました。ほとんど理解できませんが、簡単に良い文書を書きたいならこれで十分です！

それでは、私がどのようにやったかを話しましょう!

私たちの最終目標は、良いドキュメントを書くことです。したがって、まず次のことを判断する必要があります: 良い文書とは何か。

適切なドキュメントは次のとおりです:

上記のドキュメントの何が優れているのでしょうか? 第一に、それは一目で機能とパラメーターを知ることができる
ドキュメントです。第二に、それはパラメーターを入力してすぐに結果を確認できる
プログラムです。

上記のようなデバッグ可能なドキュメントを生成できることです。 次に行う必要があるのは 2 つです: 1. ドキュメントを生成します。 2. ドキュメントはデバッグ可能です。

これから始めようとしていますが、どこから始めればよいかわからない
ので、
最も具体的な

最終的にはどのようなデバッグ可能な APIを作るべきでしょうか?

簡略化して言うと、次のようになります:

プレーンテキストにはクラス名、メソッド、関数の説明、入力パラメータが表示されます。

実行結果を表示するエリアがあります。

変数
とは何ですか?

アイテムをリストする

モデル分析

API には、クラス名、クラス ファイルへのパス、メソッド名、関数の説明、メソッドに入力する必要があるパラメーターなどの属性が含まれます。

パラメータには、パラメータ名とパラメータの説明という属性も含まれます。 イベントストリーム

一言で言うと

「生成」ボタンをクリックして、クラスの HTML ドキュメントを生成します。

ここでわかりやすく説明したいので、段落
に展開しました。
生成するドキュメントのクラスとメソッドは設定ファイルで指定されており、「生成ボタン」をクリックして設定ファイルを読み込みます。その後、ドキュメントを順番に生成します。

最終デザイン システム全体には 3 種類のページがあります:
機能ページ
: API を生成するボタンは 1 つだけです。

クラスリストページ

API ページ

3種類のページのうち、2種類目のリストページは機能がなくページジャンプのみなので、HTMLでしか実装できません。 関数ページとAPIページに関しては、

を使用して設計されています。

MVC 構造

MVC 呼び出しプロセス

ユーザーがビュー レイヤーの [生成] ボタンをクリックすると、コントローラーがトリガーされます。
コントローラーは API を生成する必要があるクラスを指定し、これらのクラスで静的メソッド make_api を呼び出してモデルを生成します。

APIページ

MVC 構造

MVC 呼び出しプロセス ユーザーは View レイヤーでメソッドのパラメーターを入力し、[実行] ボタンをクリックしてコントローラーをトリガーします。
コントローラーは View ページによって渡されたパラメーターに基づいてメソッドを実行し、結果をビューに送信します
View は結果を受け取り、それを表示します
結論

私が実装したバージョンは CohenBible です。

prmd、swagger editor、apidocjs など、同様のツールが多数あり、どれも非常に便利です。
この記事を書くことは、皆さんに車輪の再発明を奨励するためのものではありませんが、もしあなた自身がそれを実行すれば、違う収穫が得られるでしょう。

なぜ車輪の再発明を考える必要があるのでしょうか?
実際、最大の理由は次のとおりです: 上記のツールの使い方がまったく分からないので、自分で実装し、ドキュメント生成プロセス全体を実行する必要がありました。その結果、上記のツールを振り返ってみると、実際にすぐに使えます！公式チュートリアルに従えば、どれくらい時間がかかるか分かりません(笑):)