Comment rédiger de la documentation et des tests API à l'aide des spécifications API Blueprint en PHP

Avec le développement rapide d'Internet, l'utilisation de l'API Web est devenue de plus en plus courante. Afin de permettre aux utilisateurs de démarrer rapidement, il est crucial de rédiger une bonne documentation et de bons tests sur l'API. API Blueprint est une spécification de document API écrite à l'aide du langage de balisage Markdown, qui peut nous aider à rédiger la documentation et les tests de l'API de manière standardisée, rendant l'API plus facile à comprendre et à utiliser. Cet article explique comment utiliser les spécifications API Blueprint pour rédiger de la documentation et des tests API en PHP.

Installer API Blueprint

Avant de commencer, nous devons d'abord installer API Blueprint. Nous pouvons introduire API Blueprint dans les projets PHP via Composer. Exécutez la commande suivante dans le terminal pour installer :

composer require apiaryio/php-codex

Rédiger la documentation de l'API

Définir les points de terminaison

L'une des principales fonctionnalités d'API Blueprint est qu'il peut nous aider à définir les points de terminaison de l'API. Nous pouvons utiliser ## pour représenter un nouveau point de terminaison d'API. Par exemple : ##表示一个新的API端点。例如：

## 用户

以下API端点针对用户进行操作。

### 获取用户列表 [GET /users]

获取用户列表。

+ Response 200 (application/json)
    + Headers
        Link: <http://example.com>; rel="self"
    + Body

            [
              {
                "id": 1,
                "username": "user1",
                "name": "User One"
              },
              {
                "id": 2,
                "username": "user2",
                "name": "User Two"
              }
            ]

上述定义了一个用户端点和获取用户列表的API端点，并且针对该API端点定义了返回数据结构和错误码等信息。

定义请求参数

我们可以使用+ Parameters来定义请求参数。例如：

+ Parameters

    + page (int, optional, default: 1) ... 页码
    + per_page (int, optional, default: 10) ... 每页数量

上述表示该API端点支持两个请求参数：page和per_page。其中page的数据类型为整型，可选项，缺省值为1；per_page的数据类型为整型，可选项，缺省值为10。

定义请求体

我们可以使用+ Request来定义请求体。例如：

+ Request (application/json)

    {
      "username": "user1",
      "password": "123456"
    }

上述表示该API端点需要传递一个JSON格式的请求体，包含username和password两个参数。

定义返回数据

我们可以使用+ Response来定义返回数据。例如：

+ Response 200 (application/json)
    + Headers
        Link: <http://example.com>; rel="self"
    + Body

            {
              "id": 1,
              "username": "user1",
              "name": "User One"
            }

上述表示该API端点的返回数据为JSON格式，包含id、username和name三个参数。

定义错误码

我们可以使用+ Response来定义错误码。例如：

+ Response 400 (application/json)
    + Headers
        Link: <http://example.com>; rel="self"
    + Body

            {
              "error": "请求参数错误"
            }

上述表示当请求参数错误时，该API端点会返回HTTP状态码为400，错误信息为请求参数错误

npm install -g dredd

Ce qui précède définit un point de terminaison utilisateur et le point de terminaison de l'API pour obtenir la liste des utilisateurs, et définit la structure des données de retour, le code d'erreur et d'autres informations pour le point de terminaison de l'API.

Définir les paramètres de la requête

Nous pouvons utiliser + Paramètres pour définir les paramètres de la requête. Par exemple :

## 用户

以下API端点针对用户进行操作。

### 获取用户列表 [GET /users]

获取用户列表。

+ Request

    + Headers

            Authorization: Token abcdefg

    + Parameters

        + page (int, optional, default: 1) ... 页码
        + per_page (int, optional, default: 10) ... 每页数量

+ Response 200 (application/json)
    + Headers
        Link: ; rel="self"
    + Body

            [
              {
                "id": 1,
                "username": "user1",
                "name": "User One"
              },
              {
                "id": 2,
                "username": "user2",
                "name": "User Two"
              }
            ]

+ Response 401 (application/json)
    + Body

            {
              "error": "您没有访问该接口的权限"
            }

+ Request

    + Headers

            Authorization: Token abcdefg

    + Body

            {
              "username": "user1",
              "password": "123456"
            }

+ Response 200 (application/json)
    + Headers
        Link: <http://example.com>; rel="self"
    + Body

            {
              "id": 1,
              "username": "user1",
              "name": "User One"
            }

+ Response 400 (application/json)
    + Body

            {
              "error": "请求参数错误"
            }

Ce qui précède indique que le point de terminaison de l'API prend en charge deux paramètres de requête : page et per_page. Le type de données de page est entier, facultatif et la valeur par défaut est 1 ; le type de données de per_page est entier, facultatif et la valeur par défaut est 10.

Définissez le corps de la requête

Nous pouvons utiliser + Request pour définir le corps de la requête. Par exemple :

dredd api.apib http://localhost:8000

Ce qui précède indique que le point de terminaison de l'API doit transmettre un corps de requête au format JSON, contenant deux paramètres : nom d'utilisateur et mot de passe.

Définir les données de retour

Nous pouvons utiliser + Réponse pour définir les données de retour. Par exemple :

rrreee

Ce qui précède indique que les données de retour du point de terminaison de l'API sont au format JSON et contiennent trois paramètres : id, username et name code>. <p></p>Définir le code d'erreur<h2></h2>Nous pouvons utiliser <code>+ Réponse pour définir le code d'erreur. Par exemple :

rrreee

Ce qui précède signifie que lorsque les paramètres de requête sont incorrects, le point de terminaison de l'API renvoie le code d'état HTTP 400 et le message d'erreur est Erreur de paramètre de demande. 🎜🎜Rédaction de tests API🎜🎜Une autre caractéristique principale d'API Blueprint est qu'il peut nous aider à écrire des tests API. Nous pouvons utiliser [Dredd](https://dredd.org/en/latest/) pour exécuter des tests API Blueprint. 🎜🎜Installez Dredd🎜🎜Exécutez la commande suivante dans le terminal pour installer : 🎜rrreee🎜Écrivez un script de test🎜🎜Nous pouvons définir le script de test dans API Blueprint. Par exemple : 🎜rrreee🎜Ce qui précède définit un point de terminaison utilisateur et le point de terminaison de l'API pour obtenir la liste des utilisateurs, et définit le script de test dans le plan de l'API, y compris l'envoi de requêtes, les réponses de vérification et les codes d'état HTTP. 🎜🎜Exécutez le script de test🎜🎜Entrez le répertoire où se trouve le Blueprint de l'API dans le terminal et exécutez la commande suivante pour tester l'API : 🎜rrreee🎜Ce qui précède signifie exécuter le script de test du Blueprint de l'API et envoyer une requête à le port local 8000 pour vérifier si l'API est conforme aux spécifications convenues. 🎜🎜Conclusion🎜🎜En utilisant les spécifications API Blueprint pour rédiger la documentation et les tests de l'API, nous pouvons définir plus clairement les points de terminaison de l'API, les paramètres de requête, les corps de requête, les données de retour, les codes d'erreur et d'autres informations, rendant l'API plus facile à comprendre et à utiliser. Dans le même temps, l'utilisation de Dredd pour les tests d'API peut garantir efficacement que l'API est conforme aux spécifications convenues. 🎜

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!