좋은 인터페이스 문서를 작성하는 방법

이 글은 좋은 인터페이스 문서를 작성하는 방법을 주로 공유합니다. 좋은 인터페이스 문서를 작성하는 데 도움이 되기를 바랍니다.

1 HTTP가 정보를 전달하는 방식

• url

• headers

• 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 데이터 모델 정의🎜🎜데이터 모델 정의에는 다음이 포함됩니다. 🎜🎜🎜🎜경로 및 쿼리 문자열 매개변수 모델🎜🎜🎜🎜요청 본문 매개변수 모델🎜🎜🎜 Response Body Parameter 모델 🎜🎜🎜🎜 데이터 모델의 최소 데이터 세트 : 🎜🎜🎜🎜 Name 🎜🎜🎜🎜 필요합니까? 🎜🎜🎜🎜 🎜🎜🎜

"최소 데이터 세트"(MDS)를 나타냅니다. 수집을 통해 설정된 최소한의 데이터는 연구 대상의 특성이나 사건, 직무의 현황을 보다 잘 파악하기 위해 사용되며, 관찰 대상에 대한 효율적이고 실용적인 데이터 지표 세트를 구축하는 것이 핵심입니다. 최소 데이터 세트의 개념은 미국의 의료 분야에서 시작되었습니다. 최소 데이터 세트의 생성은 상하위 품질 및 기술 감독 부서 간, 기업과 품질 및 기술 감독 부서 간, 품질 및 기술 감독 부서와 기업 간 정보 교환의 필요성과 같은 정보 교환의 필요성에서 비롯됩니다. 공공의.

🎜일부 문서에서는 필드 유형을 추가할 수 있지만 이는 불필요하다고 생각합니다. HTTP로 전송되는 데이터는 직렬화해야 하는 경우가 많으며 대부분의 데이터 유형은 문자열이라고 생각됩니다. 열거 유형 문자열과 같은 일부 특수 유형은 설명에 설명될 수 있습니다. 🎜🎜추가로: 데이터 모델을 표현하기 위해 테이블을 사용하는 것이 좋습니다. 🎜🎜밤 하나 주세요

위 내용은 좋은 인터페이스 문서를 작성하는 방법의 상세 내용입니다. 자세한 내용은 PHP 중국어 웹사이트의 기타 관련 기사를 참조하세요!