How to write good interface documentation

This article mainly shares with you how to write a good interface document. I hope it can help you write a good interface document.

1 How HTTP carries information

• url

• headers

• body: including request body, response body

2 Separating general information

Generally speaking, the information in headers is universal and can be stated in advance as default parameters

3 Parameter expression in the path

The parameter expression in the URL uses the mustache form, and the parameters are wrapped in double curly brackets{{paramName}}

For example:

• /api/user/{{userId}}

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

4 Data model definition

data The model definition includes:

• Path and query string parameter model

• Request body parameter model

• Response body parameter model

Minimum data set of data model:

• Name

• Whether Must

• Explanation

"Minimum Data Set" (MDS) refers to collecting the minimum amount of data to better understand a research object. The core of the characteristic or the status of a thing or a job is to establish a set of streamlined and practical data indicators for the observed object. The concept of minimal data sets originated in the medical field in the United States. The generation of the minimum data set stems from the need for information exchange, such as the need for information exchange between superior and subordinate quality and technical supervision departments, between enterprises and quality and technical supervision departments, and between quality and technical supervision departments and the public.

Some documents may add field types, but I think this is unnecessary. It is thought that the data transmitted by HTTP often needs to be serialized, and most data types are strings. Some special types, such as enumeration type strings, can be described in the description.

In addition: It is highly recommended to use tables to express the data model.

Give me a chestnut

The above is the detailed content of How to write good interface documentation. For more information, please follow other related articles on the PHP Chinese website!