Comment rédiger une bonne documentation d'interface

Cet article vous explique principalement comment rédiger un bon document d'interface. J'espère qu'il pourra vous aider à rédiger un bon document d'interface.

1 Comment HTTP transporte les informations

• url

• en-têtes

• corps : comprenant le corps de la requête, le corps de la réponse

2 Séparer les informations générales

De manière générale, les informations dans les en-têtes sont universelles et peuvent être indiquées à l'avance comme paramètres par défaut

3 Expression du paramètre dans le chemin

L'expression du paramètre dans l'URL utilise la forme d'une moustache et les paramètres sont entourés de doubles accolades {{paramName}}

Par exemple :

• /api/user/{{userId}}

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

4 Définition du modèle de données

La définition du modèle de données comprend :

• Modèle de paramètres de chemin et de chaîne de requête

• Modèle de paramètres de corps de requête

• Modèle de paramètres du corps de réponse

Ensemble de données minimum du modèle de données :

• Nom

• Est-ce nécessaire

• Explication

« Ensemble minimum de données » (MDS) fait référence à une meilleure compréhension d'un objet de recherche en collectant le moins de données possible de données L'essentiel des caractéristiques ou du statut d'une chose ou d'un travail consiste à établir un ensemble d'indicateurs de données rationalisés et pratiques pour l'objet observé. Le concept d’ensembles de données minimaux est né dans le domaine médical aux États-Unis. La génération de l'ensemble minimum de données découle du besoin d'échange d'informations, tel que le besoin d'échange d'informations entre les départements de qualité et de supervision technique supérieurs et subordonnés, entre les entreprises et les départements de qualité et de supervision technique, et entre les départements de qualité et de supervision technique et le publique.

Certains documents peuvent ajouter des types de champs, mais je pense que cela est inutile. On pense que les données transmises par HTTP doivent souvent être sérialisées et que la plupart des types de données sont des chaînes. Certains types spéciaux, tels que les chaînes de type énumération, peuvent être décrits dans la description.

Aussi : 数据模型非常建议使用表格来表现.

Donnez-moi une châtaigne

Ce qui précède est le contenu détaillé de. pour plus d'informations, suivez d'autres articles connexes sur le site Web de PHP en chinois!