優れたインターフェースドキュメントの書き方

この記事では主に、優れたインターフェイス ドキュメントの作成方法について説明します。これが、優れたインターフェイス ドキュメントの作成に役立つことを願っています。

1 HTTP が情報を運ぶ方法

• url

• ヘッダー

• body: リクエストボディ、レスポンスボディを含む

2 一般情報の分離

一般的に言えば、ヘッダー内の情報は普遍的であり、デフォルトパラメータとして事前に指定できます

3 パス内のパラメータ式

URL内のパラメータ式は口ひげ形式を使用し、パラメータは二重中括弧で囲まれています{{paramName}} code ><code>{{paramName}}

例如：

• /api/user/{{userId}}

• /api/user/{{userType}}?age={{age}}&gender={{gender}}

4 数据模型定义

数据模型定义包括：

• 路径与查询字符串参数模型

• 请求体参数模型

• 响应体参数模型

数据模型的最小数据集：

• 名称

• 是否必须

• 说明

“最小数据集”（MDS）是指通过收集最少的数据，较好地掌握一个研究对象所具有的特点或一件事情、一份工作所处的状态，其核心是针对被观察的对象建立起一套精简实用的数据指标。最小数据集的概念起源于美国的医疗领域。最小数据集的产生源于信息交换的需要，就好比上下级质量技术监督部门之间、企业与质量技术监督部门之间、质量技术监督部门与社会公众之间都存在着信息交换的需求。

一些文档里可能会加入字段的类型，但是我认为这是没必要的。以为HTTP传输的数据往往都需要序列化，大部分数据类型都是字符串。一些特殊的类型，例如枚举类型的字符串，可以在说明里描述。

另外：数据模型非常建议使用表格来表现

例:

🎜🎜🎜/api/user/{{userId}}🎜🎜🎜🎜/api/user/{{userType}}?age={{ age} }&gender={{gender}}🎜🎜🎜🎜4 データ モデル定義🎜🎜データ モデル定義には以下が含まれます: 🎜🎜🎜🎜パスおよびクエリ文字列パラメータ モデル🎜🎜🎜🎜リクエスト本文パラメータ モデル🎜🎜🎜 🎜 レスポンスボディパラメータモデル 🎜🎜🎜🎜 データモデルの最小データセット: 🎜🎜🎜🎜 名前 🎜🎜🎜🎜 必要かどうか 🎜🎜🎜🎜 説明 🎜🎜🎜

「最小データセット」(MDS) は、収集による最小限のデータセット データは、研究対象の特性、またはイベントや仕事の状態をより適切に把握するために使用されます。その核心は、観察対象に対する一連の合理化された実用的なデータ指標を確立することです。最小限のデータセットの概念は、米国の医療分野で生まれました。最小限のデータセットの生成は、上位と下位の品質・技術監督部門間、企業と品質・技術監督部門間、品質・技術監督部門と企業間の情報交換の必要性など、情報交換の必要性から生じます。公共。

🎜ドキュメントによってはフィールドタイプを追加する場合がありますが、これは不要だと思います。 HTTP によって送信されるデータはシリアル化する必要があることが多く、ほとんどのデータ型は文字列であると考えられています。列挙型文字列などの一部の特殊な型は、説明に記述することができます。 🎜🎜さらに: データ モデルを表すためにテーブルを使用することを強くお勧めします。 🎜🎜栗をください

以上が優れたインターフェースドキュメントの書き方の詳細内容です。詳細については、PHP 中国語 Web サイトの他の関連記事を参照してください。