PHPUnit + openapi-validator에서 "스키마가 양수, 구현이 추종"으로 설정

이번에 이야기하고 싶은 것

(API 개발 팀의 한 프레임)

「『구현이 정, 스키마가 추종』은 무리군요」

「『스키마가 정, 실장이 추종』하도록 하고 싶네요」

※본 기사는 Laravel/Vue.js 공부회 #10의 발표 자료입니다

하자.

PHPUnit에서 API가 스키마와 다른 응답을 반환하면 떨어지는 테스트를 작성하십시오

이를 위해 필요한 것

OpenApi

redoc-cli

PHPUnit

openapi-validator

OpenApi

스키마를 작성하기위한 대단한 yaml (JSON).

뭐 뭐 기억하는 경우가 많다.



이런 느낌

openapi: 3.0.2
info:
  title: 蔵書管理システムAPIドキュメント
  description: 蔵書管理システムのAPIドキュメントです
  version: 1.0.0
servers:
  - url: https://example.com/api
    description: 本番環境
paths:
  /books:
    get:
      summary: 本の一覧
      description: |
        登録してある本の一覧を取得できます
      operationId: getBooks
      parameters:
        - name: borrow
          in: query
          description: |
            貸出中を含める
          required: false
          schema:
            type: boolean
            example: true
      responses:
        200:
          description: 成功
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/book'
components:
  schemas:
    book:
      title: Book
      description: Bookのスキーマです。
      required:
        - id
        - title
        - created_at
        - updated_at
      type: object
      properties:
        id:
          type: integer
        title:
          type: string
        created_at:
          type: string
        updated_at:
          type: string
      example:
        id: "1"
        title: "Love beautiful code"
        created_at: "2019-07-08 15:22:15"
        updated_at: "2019-07-08 15:22:15"

Q. 뭔가 잘 모르겠지만…
A. 익숙해지면 읽을 수 있습니다! 최선을 다하십시오! !

redoc-cli

조금 전 모르는 yaml을 html로 해주는 사람

명령 한 번으로 문서를 만들 수 있기 때문에 편리합니다.
redoc-cli bundle ./resources/docs/apiV1.yml -o ~/book_sample.html


이런 느낌

openapi-validator

OpenApi의 yaml을 PHPUnit으로 가져 오는 사람

[이미지 다이어그램]

response => Validator = (OK) => Green
                      = (NG) => Red

구현해보기

(Laravel을 사용하는 전제)

OpenApi에서 스키마 작성

PHPUnit (openapi-validator)에서 스키마 호출

응답과 스키마가 다르면 RED

1. OpenApi에서 스키마 작성

최선을 다합시다!

(문서 보면서 악전 고투할 수밖에 없는 것 같은 생각이… )

이번에는 완성 된 스키마는 resources/docs/apiV1.yml에 넣습니다.

2. PHPUnit (openapi-validator)에서 스키마를 호출합니다.

이런 느낌입니다

<?php

namespace Tests\Feature;

use Tests\TestCase;
use Mmal\OpenapiValidator\Validator;
use Symfony\Component\Yaml\Yaml;


class ApiV1Test extends TestCase
{
    /** @var Validator */
    static $openApiValidator;

    public static function setUpBeforeClass()
    {
        parent::setUpBeforeClass();
        self::$openApiValidator = new Validator(Yaml::parse(file_get_contents(resource_path('docs/apiV1.yml'))));
    }

    /**
     * @test
     */
    public function getBooks()
    {
        $response = $this->get('api/book');

        $result = self::$openApiValidator->validate('getBooks', 200, json_decode($response->getContent(), true));
        $this->assertFalse($result->hasErrors(), $result);
    }
}

테스트하기 전에 OpenApi를 $openApiValidator로로드

테스트에서 "OpenApi에서 응답 정의/예상 상태 코드/응답"$openApiValidator 전달

Green or Red

실제로 해보자(Red)

응답에서 updated_at를 지우면 ...



있어야 할 속성이 없으면 화가납니다! 레드! !

실제로 해보자 (Green)

응답에 updated_at를 추가하면 ...



응답과 스키마의 정의가 동일! Green! !

시험이 다 통과한 후

redoc-cli로 스키마를 html로 공개!

마지막으로

무엇이 힘들어, OpenApi(yaml) 쓰는 것이 어쨌든 괴롭습니다 (^o^)

기존에 API가 있으면 더욱 어색합니다 (^o^)(^o^)