1: API インターフェイス ドキュメントを作成する理由
APIインターフェースドキュメントは、開発過程で他の協力者が一緒にデバッグするための重要なツールです.操作マニュアルのようなものです.アイテムを与えられた場合、その使い方がわからないかもしれませんが、操作マニュアルがあれば、アイテムを手に入れたばかりの人に、すぐにアイテムを使用させることができます。同様に、API インターフェイス ドキュメントは、他のライターがインターフェイス呼び出し操作をすばやく理解し、すばやく使用し、実行するためのマニュアルです。
たとえば、プログラマーは他の人がインターフェイス ドキュメントを書かないことを嫌います; プログラマーはインターフェイス ドキュメントを書くのが一番好きではありません...
実際、矛盾していますが、インターフェイス ドキュメントの重要性も反映しています。
幸いなことに、私はサードパーティ システムに接続することが多いため、多くのインターフェイス ドキュメントを受け取りました. それらの _ フォームは、さまざまな種類の奇妙なものであり、それぞれに独自の利点があり、標準的なものもあれば、読みにくいものもあります. _
2: 一般的な文書形式
一般的なドキュメントには次の形式があります
1. webServer ドキュメント形式
- WebServerドキュメントは、ショッピングモールや金融システムなどで一般的に使用されており、業務実装のロジック図やWebサービスの配信記述（サービス名、提供メソッド、メソッドのパラメータ情報など、Webサービスのインターフェースを定義したもの）などが一般的です。
- リクエストの形式は通常 POST です。
- 通常、データ形式は XML です。
2. Swagger-UI スタイルのドキュメント
このようなドキュメントは、オンライン インターフェイス編集を実現し、後続のインターフェイス テスト コールを実装するためのトークンを自動的に生成し、一般に RESTFUL インターフェイス仕様に基づいています。
このタイプのインターフェースは、インターフェースが使用可能かどうかを視覚的に確認できます。
アドレス: https://teevid.github.io/mwapi/index/
3.SDK ドキュメント
タイトルに示すように、相手側はインターフェイス操作を特定の SDK パッケージにカプセル化します。呼び出し側は SDK をインスタンス化するだけでよく、ドキュメントを参照してメソッドを呼び出すことができます。この方法はよりシンプルで、ドッキングのコストは低くなりますが、プロバイダーは対応する言語の SDK を提供する必要があります。これには一定の開発圧力があります。
4. オンライン API ドキュメント
このような API については、 Weifutong、Gaode Maps、Meituan API、Douyin APIなどのオンライン ドキュメントを参照できます。このようなドキュメントは基本的な形式が同じで普遍的であり、通常、さまざまな開発言語による呼び出しに対して http/https 要求を提供します。
5. API インターフェイスのワード文書
このタイプのインターフェースは、一般に、以下で説明する API ドキュメントを提供するための民営化開発に使用されます。
各社が提供するドキュメントの仕様は異なり、RESTFUL スタイルに準拠したものもあれば、一律に POST 形式のインターフェースを直接出力するものもあります。
3: API インターフェイス Word ドキュメントには何を含める必要がありますか?
非標準のインターフェイス ドキュメントの場合、これは本当に頭の痛い問題です.たとえば、API ドキュメントを受け取ったことがあります.署名の暗号化アルゴリズムであり、ドキュメントは 4 つのステップで記述されていました.しかし、手順に従って暗号化すると、正しい値、確認を繰り返した後、役に立たなかったので、相手の関連開発者と調整して支援しましたが、恐ろしいことが起こり、一緒にデバッグした後、暗号化の手順は非常に高かった14ステップ。
文書に例があるかどうかは言うまでもなく、あったとしても神々は意思疎通できない。
1.変更記録
変更履歴があるのはいいことですが、いつ、誰が、どの内容を変更したのか、まずはこのバージョンでどのインターフェースが更新されたのかを他の共同作業者が把握できると便利です。もちろん、何か問題が発生した場合、トレーサビリティの役割も非常に重要です。
2. 文書の目的
このドキュメントが使用される目的は、一般的に、民営化展開の開発者とユーザーの間の協力の内容を紹介することです。
3. インターフェース仕様
このセクションでは、一般に、送信方法 (http/https)、提出方法 (インターフェース仕様、安らかなスタイルまたはすべてのポスト)、データ形式、文字エンコーディング、署名アルゴリズム、テスト環境アドレスなどのオープン インターフェース仕様を紹介します。
4. システムパラメータ/公開パラメータ
システムパラメーターは、各インターフェースによって運ばれるパラメーターであり、各インターフェースの基本情報を記述し、統計やその他の目的で使用され、通常はヘッダーまたは url パラメーターに配置されます。
| パラメータ | 例証する |
|---|---|
| バージョン | バージョン番号 (バージョン管理) |
| 時間 | タイムスタンプ (アンチリプレイ) |
| から | ソース (アクセス元のインターフェース、h5/アプレット) |
| サイン | サイン |
5. 署名アルゴリズム
これは非常に重要なステップです. 優れた署名アルゴリズム ドキュメントの場合, ステップは明確でなければなりません, そして、各ステップは例で示されなければなりません. 最終的に得られた署名を検証することができます.
6. 標準化されたビジネス コーディング
一般に、安らかなスタイルによれば、戻り値にはコード、メッセージ、およびデータが含まれます; コードが 200 の場合、インターフェイスは正しく、残りのコード値はすべてエラーです; 一般的に、間違った戻り値
コード表に表示する必要があります。
7. 特定のインターフェイスにはパラメータが必要です
7.1 インターフェース名
これについて説明する必要はありません。正しいインターフェイス名は非常に重要です。
7.2 インターフェースの紹介
このインターフェースが達成するために使用する機能。
7.3 インターフェースリクエストフォーマット
RESTFUL スタイルに基づいて、POST、GET、PUT、DELETE の各インターフェイスでインターフェイスのリクエスト形式を示す必要があります。
7.4 インターフェースアドレス
インターフェースのAPIアドレスです
7.5 インターフェース入力パラメータ
フィールド名、必須かどうか、フィールド属性、フィールドの説明など、入力パラメーターの説明。
7.6 インターフェース出力・戻り値
フィールド名、必須かどうか、フィールド属性、フィールドの説明など、パラメーターの説明。
7.7 リクエスト例
通常、ドメイン名またはテストアドレスを一緒に綴ることをお勧めします
7.8 入力パラメータの例
次のように
7.9 パラメータの例
次のように
4: API インターフェイス ドキュメントの例
5:終了
この記事は、主に 3 者と協力して行った最近の経験をまとめ、他の人が明確に理解できるようにインターフェイス ドキュメントの説明をまとめ、すべての人に役立つことを願っています。より良いドキュメント ライティングの仕様があれば、それを私に提案することもできます。
メッセージ
ルールがあるから世界は美しい