インターフェース設計書を共有する際の12の注意点

はじめに

私たちはバックエンド開発を行っており、インターフェイス ドキュメントを定義する必要がよくあります。

最近 インターフェイス ドキュメントのレビュー を行っていたとき、小規模パートナーによって定義された パラメータが列挙値 であることがわかりましたが、インターフェイス ドキュメントには 対応する特定の列挙値 。実際、インターフェイスドキュメントをうまく書く方法は非常に重要です。今日は、Tianluo 兄弟がインターフェイス設計ドキュメントに関する 12 の注意点をお届けします~

• ##パブリック アカウント : カタツムリを拾う少年 (カタツムリに関する丁寧なオリジナルのインタビュー PDF があります)
github アドレス、すべてのスターに感謝します:
• github

1. インターフェース名は明確ですか?

言い換えれば、あなたのインターフェースは何をするもので、理解しやすく明確ですか?一般的なインターフェイス

urlでは、インターフェイスの機能が見える必要もあります。たとえば、ユーザー情報のクエリ (queryUserInfo) は、適切なインターフェイス名 です。

2. インターフェイス アドレスは完了していますか?

インターフェイスのアドレスは、インターフェイスの

URL アドレスとも呼ばれます。つまり、他の人があなたのインターフェースを呼び出すときに URL が使用されるということです。たとえば、/api/user/queryUserInfo は インターフェイス アドレス です。ただし、ここで言いたいのは、これは完全なインターフェイス アドレスではないということです。インターフェイスは HTTP という名前ですか?

HTTP が呼び出された場合、ドメイン名 は何ですか? ＃＃＃ポート＃＃＃。適切な http インターフェイス アドレスは次のようになります:

https//tianluo.com:15000/api/user/queryUserInfo

3. インターフェイスのリクエスト メソッドは正しいですか?

インターフェイスのリクエスト メソッドには通常、次のものが含まれます:

GET: リソースを取得するためサーバーから、

URL

でパラメータを渡すことができます。これは通常、データのクエリに使用されます。
• POST: データをサーバーに送信します。通常、追加、変更、削除などの操作に使用されます。
PUT: リソースをサーバーに更新します。通常はデータの更新に使用されます。
• DELETE: サーバーからリソースを削除します。通常はデータの削除に使用されます。
• PATCH: サーバーのリソースを部分的に更新します。通常は一部のデータを変更するために使用されます。
• HEAD:
• GET
リクエストと似ていますが、エンティティのコンテンツではなく応答ヘッダーのみを返します。通常、リソースのメタ情報を取得するために使用されます。
• オプション: サポートされているリクエスト メソッドとその他の情報を返すようにサーバーに要求します。通常、クライアントとサーバーがリクエスト メソッドをネゴシエートするために使用されます。
• インターフェイス ドキュメントを定義するときは、インターフェイスのリクエスト メソッドがどれであるかを明確に記述する必要があります。通常の状況では、
POST と GET

をより頻繁に使用します。すべてのインターフェイスに

POST を使用する企業もあります。

#4. リクエスト パラメータの 8 つの主要要素

インターフェースを定義するとき、リクエスト パラメータは

最も重要な部分の 1 つです

。修飾されたインターフェイス ドキュメントの場合、リクエスト パラメーターには次の 8 つの要素が含まれている必要があります。

パラメーター名: パラメーターの名前は、userId

のようにキャメル ケースで付けられます。

• Type: String、Integer などのパラメータのタイプ。
• Required: リクエスト パラメータが必須かどうか。必要な場合、アップストリームがこのパラメータを渡さない場合、パラメータ検証例外がスローされる必要があります。 デフォルト値: このパラメータが渡されない場合、デフォルト値はありますか、またデフォルト値は何ですか。
• 値の範囲:
Long、Integer
• などの数値型の場合は、列挙型の場合は
1~10
• などの範囲値になります。 value、これは、ACTIVE、INACTIVE などの列挙範囲です。 パラメータ形式: たとえば、パラメータが日付の場合は、yyyyMMdd
• などのパラメータ形式を指定する必要があります。入力パラメータの値の例: 例を提供します。応答パラメーターの値。これにより、開発者はこのパラメーターをよりよく理解し、使用できるようになります。 備考: この入力パラメータ フィールドに
特別な指示
• がある場合は、この列で説明できます。特に説明がなければ、このパラメータの機能を説明するだけで大​​丈夫です。
• 以下はパラメータを入力するためのサンプルドキュメントです
:

#パラメータ名タイプ必須かどうかデフォルト値値の範囲パラメータ形式入力パラメータ値例備考(説明)userId Long は #0L0~99999999Lなし666LUserIdbirthDay文字列は1990010119900101~20231231yyyyMMdd 19940107ユーザーの誕生日

##5. 応答パラメータの 7 つの主要要件

応答パラメータは実際には次のとおりです。入力パラメータと同様に、7 つの要素があります:

パラメータ名: 応答パラメータの名前を記述します。

• パラメータ タイプ:
String、Integer
• などの応答パラメータのデータ タイプを記述します。 パラメータ形式:
yyyy-MM-dd、HH:mm:ss
• などの応答パラメータのデータ形式を記述します。 パラメータの説明: 応答パラメータの意味の詳細な説明。
• 値の範囲:
整数範囲、文字列長
• などの応答パラメータの値の範囲を説明します。 Required: 応答パラメータが必須かどうかを説明します。
• サンプル値: 開発者がこのパラメーターをよりよく理解して使用できるように、この応答パラメーターのサンプル値を提供します。
• 違いは、応答パラメーターが通常

code, msg, data

: <div class="code" style="position:relative; padding:0px; margin:0px;"><pre class='brush:php;toolbar:false;'>{ &quot;code&quot;: 0, &quot;message&quot;: &quot;success&quot;, &quot;data&quot;: { &quot;name&quot;: &quot;Tom&quot;, &quot;age&quot;: 20, &quot;gender&quot;: &quot;男&quot; } }</pre><div class="contentsignin">ログイン後にコピー</div></div>6 の形式で返されることです。インターフェイス エラー コード

優れたインターフェイスドキュメントには、エラーコードの列挙が含まれている必要があります。一般的なエラー コード定義には 3 つの列が含まれます:

エラー コード、エラー コード情報、意味

##エラー コードエラー情報意味##1001パラメータエラーユーザーは存在しません1003データベース エラーデータベース アクセス エラー

7.接口安全

定义接口文档时，对于一些需要保护的接口，也需要考虑接口的安全，例如权限管理、防止 SQL 注入等。

因此，接口文档应当包含接口的安全性说明：例如接口的访问授权方式、数据传输加密方式等。此外，接口文档还应该对于敏感数据和操作进行标注，方便使用者注意隐私和安全问题。

8. 接口版本管理

在接口文档定义时，接口版本管理是非常重要的一个方面。由于软件项目的迭代和升级，接口可能会随着版本的变化而发生变化。为了避免接口变化给用户带来不必要的困扰，需要对接口进行版本管理。

以下是一些常用的接口版本管理方法：

• 在接口文档中明确版本号：在接口文档中明确标识接口的版本号，例如在接口地址中添加版本号信息，如https://example.com/api/v1/user，表示该接口的版本号为v1。
• 使用语义化版本号：采用语义化版本号（Semantic Versioning）规范，即版本号格式为X.Y.Z，其中X表示主版本号、Y表示次版本号、Z表示修订号。当进行兼容性变更时，需升级主版本号；当增加功能且不影响现有功能时，需升级次版本号；当进行bug修复或小功能改进时，需升级修订号。
• 增量发布：在接口发生变化时，先发布新版本的接口，同时保留旧版本的接口。用户可以根据自己的需求来选择使用哪个版本的接口。随着新版本的接口逐步替换旧版本的接口，最终可以将旧版本的接口废弃。

无论采用何种方法，接口版本管理都应该得到充分的考虑。在接口版本变化时，需要及时更新接口文档（详细描述版本的变化、兼容性问题、版本切换方式等），以确保用户能够获得最新的接口信息。

9. 维护接口文档更新迭代

如果接口发生了变更，比如参数有哪些变更，错误码变更等等，都需要维护到文档上。同时需要登记变更的记录。

不正なリクエストパラメータ		1002
指定されたユーザー ID に基づいて、対応するユーザー情報が見つかりませんでした

日期	变更描述	操作人
2023-04-16	创建接口文档，定义了第一版接口文档	捡田螺的小男孩
2023-04-18	修改接口文档，增加了错误码，出参等	田螺哥

10.明确请求头有哪些

接口文档，是需要写清楚的请求头的。接口文档的请求头可以看到以下的信息：

• Content-Type：指定请求体的数据格式，如application/json、application/x-www-form-urlencoded、multipart/form-data等。
• Authorization：用于身份验证的令牌信息，如Token、Bearer等。
• Accept：指定客户端可以接受的响应数据格式，如application/json、text/html等。
• User-Agent：指定客户端的类型和版本信息，可以用于服务端进行针对性优化。
• Accept-Encoding：指定客户端可以接受的数据压缩格式，如gzip、deflate等。
• Cache-Control：指定客户端缓存的策略，如no-cache、max-age等。
• Cookie：包含客户端发送给服务器的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"}

11 接口请求示例

接口文档，需要提供接口的使用案例：以方便开发者理解接口的使用方法和调用流程。

12. 接口测试

一般来说，接口文档需要完善：接口测试的方法和测试结果，以便用户可以测试接口是否符合自己的需求，让用户用得放心~哈哈

以上がインターフェース設計書を共有する際の12の注意点の詳細内容です。詳細については、PHP 中国語 Web サイトの他の関連記事を参照してください。