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

はじめに

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

:

{ "code": 0, "message": "success", "data": { "name": "Tom", "age": 20, "gender": "男" } }

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

7.接口安全

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

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

8. 接口版本管理

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

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

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

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

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

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

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. 接口测试

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