私たちはバックエンド開発を行っており、インターフェイス ドキュメントを定義する必要がよくあります。
最近 インターフェイス ドキュメントのレビュー を行っていたとき、小規模パートナーによって定義された パラメータが列挙値 であることがわかりましたが、インターフェイス ドキュメントには 対応する特定の列挙値 。実際、インターフェイスドキュメントをうまく書く方法は非常に重要です。今日は、Tianluo 兄弟がインターフェイス設計ドキュメントに関する 12
の注意点をお届けします~
urlでは、インターフェイスの機能が見える必要もあります。たとえば、
ユーザー情報のクエリ (queryUserInfo) は、適切なインターフェイス名 です。
URL アドレスとも呼ばれます。つまり、他の人があなたのインターフェースを呼び出すときに
URL が使用されるということです。たとえば、
/api/user/queryUserInfo は
インターフェイス アドレス です。ただし、ここで言いたいのは、これは完全なインターフェイス アドレスではないということです。インターフェイスは HTTP という名前ですか?
HTTP が呼び出された場合、
ドメイン名 は何ですか? ###ポート###。適切な http インターフェイス アドレスは次のようになります:
3. インターフェイスのリクエスト メソッドは正しいですか?
インターフェイスのリクエスト メソッドには通常、次のものが含まれます:GET: リソースを取得するためサーバーから、
URLPOST: データをサーバーに送信します。通常、追加、変更、削除などの操作に使用されます。
オプション: サポートされているリクエスト メソッドとその他の情報を返すようにサーバーに要求します。通常、クライアントとサーバーがリクエスト メソッドをネゴシエートするために使用されます。
POST を使用する企業もあります。
インターフェースを定義するとき、リクエスト パラメータは
最も重要な部分の 1 つですパラメーター名: パラメーターの名前は、userId
のようにキャメル ケースで付けられます。String、Integer
などのパラメータのタイプ。
デフォルト値: このパラメータが渡されない場合、デフォルト値はありますか、またデフォルト値は何ですか。 ACTIVE、INACTIVE
などの列挙範囲です。
パラメータ形式: たとえば、パラメータが日付の場合は、yyyyMMdd
備考: この入力パラメータ フィールドに タイプ | 必須かどうか | デフォルト値 | 値の範囲 | パラメータ形式 | 入力パラメータ値例 | 備考(説明) | |
---|---|---|---|---|---|---|---|
Long | は | #0L | 0~99999999L | なし | 666L | UserId | |
文字列 | は | 19900101 | 19900101~20231231 | yyyyMMdd | 19940107 | ユーザーの誕生日 |
##5. 応答パラメータの 7 つの主要要件
パラメータ形式:
パラメータの説明: 応答パラメータの意味の詳細な説明。 : <pre class="brush:php;toolbar:false">{
"code": 0,
"message": "success",
"data": {
"name": "Tom",
"age": 20,
"gender": "男"
}
}</pre>
6 の形式で返されることです。インターフェイス エラー コード
意味 | ||||||||||
---|---|---|---|---|---|---|---|---|---|---|
不正なリクエストパラメータ | 1002 | |||||||||
指定されたユーザー ID に基づいて、対応するユーザー情報が見つかりませんでした | 1003 | データベース エラー | ||||||||
日期 | 变更描述 | 操作人 |
---|---|---|
2023-04-16 | 创建接口文档,定义了第一版接口文档 | 捡田螺的小男孩 |
2023-04-18 | 修改接口文档,增加了错误码,出参等 | 田螺哥 |
接口文档,是需要写清楚的请求头的。接口文档的请求头可以看到以下的信息:
application/json、application/x-www-form-urlencoded、multipart/form-data
等。Token、Bearer
等。application/json、text/html
等。gzip、deflate
等。no-cache、max-age
等。cookie
信息。这是是一个接口文档的请求头的示例:
POST /api/user HTTP/1.1 Host: example.com Content-Type: application/json Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c Accept: application/json User-Agent: Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/96.0.4664.110 Safari/537.36 Accept-Encoding: gzip, deflate, br Cache-Control: no-cache Cookie: _ga=GA1.2.1234567890.1234567890; _gid=GA1.2.0987654321.0987654321 If-None-Match: W/"2a-3TjT7VaqgkT1nJdKjX9Cpijp2FA" Referer: https://example.com/login Origin: https://example.com Content-Length: 43 {"name": "John Doe", "age": 25, "email": "john.doe@example.com"}
接口文档,需要提供接口的使用案例:以方便开发者理解接口的使用方法和调用流程。
一般来说,接口文档需要完善:接口测试的方法和测试结果,以便用户可以测试接口是否符合自己的需求,让用户用得放心~哈哈
以上がインターフェース設計書を共有する際の12の注意点の詳細内容です。詳細については、PHP 中国語 Web サイトの他の関連記事を参照してください。