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

この記事は何についてですか?

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

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

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

何をするか？

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

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

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

それで、私が望んでいるのは、コードが完成した後、非常に少ない労力で

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

どうやってするの？

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

もの、つまり現時点で唯一表示されているデバッグ可能な API から始めましょう。

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

前のレンダリングを参照して、

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

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

実行ボタンがあります。

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

このインターフェースでは、

変数
とは何ですか?

クラス名

アイテムをリストする

メソッド名

機能説明

パラメータの数

パラメータ名

実行結果

そのうち: API はクラス名、メソッド名、関数の説明、複数のパラメーター名に対応し、実行後に実行結果が生成されます。

モデル分析

上記の結果に基づいて、この API をモデル クラスに抽象化できます。

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

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

次に、トランザクションプロセス全体を分析しましょう。

一言で言うと

プロセス:

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

これが私たちがやりたいことですが、非常に不明確です。あるクラスの、あるメソッドに対応するHTML文書を生成したいのですが、一文で明確に説明できません。

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

すべての手順が完了するまで、この方法で拡張を続けます。

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

クラスリストページ

: クラスとそのメソッドをリストし、クリックすると API ページにジャンプします。

API ページ

: メソッドの説明がリストされ、パラメータを入力してメソッドを実行したり、実行結果を表示したりできます。

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

MVCパターン

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

機能ページ

MVC 構造

モデル:API;ビュー:make_api_template.php;コントローラー:create_api.php

MVC 呼び出しプロセス

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

コントローラーはこれらの Models Generate ドキュメントを使用します

APIページ

MVC 構造

モデル: まだ独立した​​モデルを形成していない js コードビュー: 生成された HTML ページ。

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

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

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

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

どんなに難しくても、API の方法を教えてください