PHP에서 API Blueprint 사양을 사용하여 API 문서 및 테스트를 작성하는 방법

인터넷의 급속한 발전으로 인해 웹 API의 사용이 점점 더 보편화되었습니다. 사용자가 빠르게 시작할 수 있도록 하려면 좋은 API 문서와 테스트를 작성하는 것이 중요합니다. API Blueprint는 Markdown 마크업 언어를 사용하여 작성된 API 문서 사양으로, 표준화된 방식으로 API 문서와 테스트를 작성하는 데 도움이 되어 API를 더 쉽게 이해하고 사용할 수 있습니다. 이 문서에서는 API Blueprint 사양을 사용하여 PHP에서 API 문서 및 테스트를 작성하는 방법을 소개합니다.

API Blueprint 설치

시작하기 전에 먼저 API Blueprint를 설치해야 합니다. Composer를 통해 PHP 프로젝트에 API Blueprint를 도입할 수 있습니다. 설치하려면 터미널에서 다음 명령을 실행하세요.

composer require apiaryio/php-codex

API 문서 작성

엔드포인트 정의

API Blueprint의 주요 기능 중 하나는 API 엔드포인트를 정의하는 데 도움이 된다는 것입니다. ##를 사용하여 새 API 엔드포인트를 나타낼 수 있습니다. 예: ##表示一个新的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

위에서는 사용자 목록을 얻기 위한 사용자 끝점과 API 끝점을 정의하고 API 끝점에 대한 반환 데이터 구조, 오류 코드 및 기타 정보를 정의합니다.

요청 매개변수 정의

+ 매개변수를 사용하여 요청 매개변수를 정의할 수 있습니다. 예:

## 用户

以下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": "请求参数错误"
            }

위는 API 엔드포인트가 page 및 per_page라는 두 가지 요청 매개변수를 지원함을 나타냅니다. page의 데이터 유형은 정수이며 선택 사항이며 기본값은 1입니다. per_page의 데이터 유형은 정수이고 선택 사항이며 기본값은 10입니다.

요청 본문 정의

+요청을 사용하여 요청 본문을 정의할 수 있습니다. 예:

dredd api.apib http://localhost:8000

위는 API 엔드포인트가 username 및 password라는 두 매개변수가 포함된 JSON 형식의 요청 본문을 전달해야 함을 나타냅니다.

반환 데이터 정의

+ Response를 사용하여 반환 데이터를 정의할 수 있습니다. 예:

rrreee

위는 API 엔드포인트의 반환 데이터가 JSON 형식이고 id, username 및 name라는 세 가지 매개변수가 포함되어 있음을 나타냅니다. 코드>.

오류 코드 정의

+ Response를 사용하여 오류 코드를 정의할 수 있습니다. 예:

rrreee

위는 요청 매개변수가 잘못된 경우 API 엔드포인트가 HTTP 상태 코드 400을 반환하고 오류 메시지는 요청 매개변수 오류라는 의미입니다. 🎜🎜API 테스트 작성🎜🎜API Blueprint의 또 다른 주요 기능은 API 테스트를 작성하는 데 도움이 된다는 것입니다. [Dredd](https://dredd.org/en/latest/)를 사용하여 API Blueprint 테스트를 실행할 수 있습니다. 🎜🎜Dredd 설치🎜🎜설치하려면 터미널에서 다음 명령을 실행하세요. 🎜rrreee🎜테스트 스크립트 작성🎜🎜API Blueprint에서 테스트 스크립트를 정의할 수 있습니다. 예: 🎜rrreee🎜위에서는 사용자 목록을 얻기 위한 사용자 엔드포인트와 API 엔드포인트를 정의하고 요청 전송, 확인 응답 및 HTTP 상태 코드를 포함하여 API Blueprint에 테스트 스크립트를 정의합니다. 🎜🎜테스트 스크립트 실행🎜🎜터미널에서 API Blueprint가 있는 디렉터리에 들어가서 다음 명령을 실행하여 API를 테스트합니다. 🎜rrreee🎜위는 API Blueprint의 테스트 스크립트를 실행하고 다음으로 요청을 보내는 것을 의미합니다. API가 합의된 사양을 준수하는지 확인하기 위해 로컬 포트 ​​8000을 사용합니다. 🎜🎜결론🎜🎜API Blueprint 사양을 사용하여 API 문서 및 테스트를 작성하면 API 엔드포인트, 요청 매개변수, 요청 본문, 반환 데이터, 오류 코드 및 기타 정보를 더 명확하게 정의하여 API를 더 쉽게 이해하고 사용할 수 있습니다. 동시에 API 테스트에 Dredd를 사용하면 API가 합의된 사양을 준수하는지 효과적으로 확인할 수 있습니다. 🎜

위 내용은 PHP에서 API Blueprint 사양을 사용하여 API 문서 및 테스트를 작성하는 방법의 상세 내용입니다. 자세한 내용은 PHP 중국어 웹사이트의 기타 관련 기사를 참조하세요!