OpenAPI 3.0 및 Prism Mock Server를 사용한 프런트엔드 애플리케이션 개발 시간 단축

개발 과정에서 자주 마찰되는 부분은 API 엔지니어와 전방 개발자 사이이다.일반적으로 프런트엔드 개발자는 API 엔드포인트가 완료될 때까지 기다린 다음 작업에 통합해야 합니다.이렇게 하더라도 API 엔지니어는 단점을 변경할 수 있고 전방 개발자는 통합을 재검토해야 한다.이것은 다시 인코딩하는 데 시간을 낭비해서 전방 개발자들을 더욱 낙담하게 할 것이다.

요점을 요약하고 다시 말하다.

본고에서 우리는 API First 디자인 과정을 연구했고 우리가 배운 개념을 간단한 충성도 응용 프로그램에 응용했다.또한 각 끝점과 최상위 세부사항을 나열하는 API 초안을 작성했습니다.

이 게시물

이 문서에서 API 스케치를 OpenAPI 3.0 정의로 변환합니다.이 문서는 모든 단점의 조작 방식을 더욱 상세하게 설명합니다. RequestBody/responseBody에 어떤 속성을 포함해야 하는지, 조회나 경로 파라미터가 있어야 하는지 등입니다.
API 엔지니어와 프런트엔드 개발자가 API를 기획하는 것부터 시작하도록 함으로써 프런트엔드-백엔드 상호작용에 대한 대량의 사고는 이미 앞당겨 완성되었다.API 정의는 API를 어떻게 조작해야 하는지에 대한 두 개발자 간의'계약'역할을 한다.어떠한 개발 전에 이'계약'을 처리함으로써 우리는 API에 대한 변경을 최대한 줄이고 개발자에게 그들의 프로젝트를 어떻게 실현하는지 지도할 수 있다.

[1] 우리 머리를 찔러 넣자!🌊

너무 많은 개념에 빠지기 전에 OpenAPI 정의를 작성해 보겠습니다.다른 탭에서 브라우저Swagger editor를 엽니다.swagger 편집기를 사용하면 브라우저를 사용하여 OpenAPI 정의를 쉽게 만들 수 있습니다.

(1.1)

Swagger 편집기 왼쪽의 기본 컨텐트를 비우고 다음 코드 세그먼트를 배치합니다.

openapi: 3.0.0 
info:
  title: Loyalty Card API
  version: "0.1"
paths: {}

이 코드 세그먼트는 OpenAPI 정의 버전과 API에 대한 최상위 수준의 정보를 설명합니다.우리는 일부러 paths 키를 빈 값으로 남겨 두었기 때문에 오류가 발생하지 않을 것이다.
오른쪽 업데이트에 시각적 문서를 입력할 때API 정의의 구문 오류도 알려 줍니다.지금, 그것은 마땅히 이렇게 해야 한다.

(1.2)

그런 다음 API의 모드를 정의합니다.에서 알 수 있듯이 표준 단점은 API의 자원을 둘러싸고 일치하는 인터페이스를 정의한다. 즉, 사무를 만들고, 사무를 읽고, 모든 사무를 읽고, 편집하는 것이다.
패턴 부분에서 우리는 이 자원의 외관을 정의한다. 어떤 속성과 모든 속성의 데이터 형식이 있는지.이 점에서 자원은 데이터베이스 모델과 같아야 한다고 할 수 있다.사실은 그렇지 않다.우리는 일부 속성을 생략할 수 있다. (즉, 우리는 모든 업무의 속성을 표시하지 않기로 선택했다. approval_code.) 심지어는 사무 자원을 사무표에 완전히 표시하지 못하게 할 수도 있다.
처음에는 사무 API와 사무 데이터베이스 테이블이 비슷할 수 있지만 시간이 지날수록 차이가 클 수 있다.

components:
  schemas:
    Transaction:
      type: object
      properties:
        id:
          type: string
        amount:
          type: number
        equivalent_points:
          type: number
        card_id:
          type: string
        partner_id:
          type: string

이제 API가 다음과 같아야 합니다.

(1.3)

이제 고기를 봅시다.🥩 API 정의: paths.경로 API 끝점에 대한 URL 경로를 정의합니다.다음 코드 세션으로 이 줄을 바꿉시다. paths: {}

# remember to replace paths: {}
paths:
  /transactions:
    post:
      summary: create transaction
      tags:
        - Transactions
      requestBody:
        content:
          application/json:
            schema: 
              $ref: '#/components/schemas/Transaction'
      responses:
        '201':
          description: Created user
          headers:
            Location:
              schema:
                type: string

코드 세션에서, 우리는 사무를 만들기 위한 경로를 정의했다. POST /transactions

summary - 끝점에 대한 간략한 정보

tags - 오른쪽 문서

requestBody - 각 유형의 내용에 대해 우리는 서로 다른 모델을 정의할 수 있다.이 예에서 우리는 응용 프로그램/json 내용

이 있다.

responses - 각 유형의 응답 유형(HTTP 201은 객체 작성, HTTP 500은 내부 서버 오류 등)에 대해 다양한 응답 형식을 정의할 수 있습니다.이 예에서 HTTP 201 생성을 요청하면 "Location"

이라는 제목의 빈 응답을 반환합니다.

(1.4)

다음은 GET /transactions 경로를 정의합니다.이 코드 세그먼트를 1.3의 코드 세그먼트 바로 아래에 추가해야 합니다.

# add this under paths
  # add this under /transactions
    get:
      summary: get all transactions
      tags:
        - Transactions
      parameters:
        - name: "partner_id"
          in: "query"
          description: ""
          required: false
          schema:
            type: integer
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  items:
                    type: array
                    items:
                      $ref: '#/components/schemas/Transaction'

이 코드는 좀 다르다.우리는 요청 주체를 정의하지 않고 검색 매개 변수를 정의했다. /transactions?partner_id=10쿼리 매개 변수는 특정 합작 파트너가 발표한 모든 거래를 전방에서 얻을 수 있도록 합니다.
이것은 GET 요청이기 때문에, 우리는 약간의 보답을 얻기를 희망한다.응답에서 요청이 성공하면 (HTTP 200) 사무 대상 그룹으로 돌아가는 것을 보았습니다.

(1.5)

일단 우리가 사무(1.3)를 만들고 모든 사무(1.4)를 볼 수 있다면, 우리는 하나의 사무를 보는 방법이 필요하다.다음 코드 세션에서, 우리는 바로 이렇게 했다.

# add this under paths
  /transactions/{id}:
    parameters:
      - schema:
          type: integer
        name: id
        in: path
        required: true
    get:
      summary: View Transaction
      tags:
        - Transactions
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Transaction'

이 코드 세그먼트에서, 우리는 path 파라미터를 사용하여 우리가 보고 있는 업무의 id를 정의합니다.이 응답은 1.4와 유사하지만, 대상 그룹이 아닌 대상을 되돌려줍니다.
이제 편집기의 오른쪽은 다음과 같습니다.

이때 API 초도에 다른 모든 리소스가 포함되지 않은 이유를 알고 싶을 수 있습니다.이것은 블로그의 게시물을 매우 크게 할 것이다.나는 사무 자원에 중점을 두기로 선택했다.나는 다른 자원에 대한 API 생성을 숙제로 정의합니다.곤경에 빠지거나 빠른 참고를 원한다면 단순 로얄티 프로그램의 완전한 오픈 API 3.0 정의 at this Github Gist 를 찾을 수 있습니다.

[2] 프리즘이 있는 아날로그 서버

이 단계에서는 1단계에서 생성한 API 정의를 사용하여 로컬에서 아날로그 서버를 실행합니다.이를 위해 Prism, NodeJS CLI 유틸리티를 사용하여 아날로그 서버를 실행합니다.

(2.1)

우선 prism을 설치합니다.

npm install --global @stoplight/prism-cli

(2.2)

파일을 "blog api.oas.yml"로 로컬로 저장하고 cd 명령줄에 있는 디렉토리에 저장합니다.추가했습니다.oas 확장자는 OpenAPI 형식의 YAML 파일임을 나타냅니다.

(2.3)

이제 Prism 에뮬레이션 서버를 실행하겠습니다.

prism mock -p 8080 ./blog_api.oas.yml

CLI는 다음과 같습니다.

지금 브라우저에 이것을 입력해 보세요: http://127.0.0.1:8080/transactions/495.너는 반드시 매우 기본적인 대답을 보아야 한다.

이제 완전히 조작 가능한 아날로그 서버를 사용할 수 있습니다.API 엔지니어가 업무 논리를 개발할 때까지 기다릴 필요가 없습니다. 당신의 전방 개발자는 즉시 전방 코드를 작성하기 시작할 수 있습니다.

[3] 추가 수당

만약 이것이 API 우선 설계를 설득하기에 부족하다면, 여기에는 또 다른 장점이 있습니다.이러한 혜택은 우리가 앞의 두 단계에서 사용한 Swagger editor의 기능이다.

[1] 미리 생성된 백엔드

API 엔지니어는 API 정의만 사용하면 전체 API 백엔드 시스템을 미리 생성할 수 있습니다.이것은 응용 프로그램의 경로와 경로를 설정하는 많은 시간을 절약했다.

생성된 응용 프로그램은 업무 논리가 없습니다.그것은 샘플 응답을 되돌려 주는 캐시 루트로 구성되어 있습니다.그런데 이런 비계는 빨리 서고 달리는 데 큰 도움이 돼요.

[2] SDK 사전 생성

API 엔지니어는 SDK(소프트웨어 개발 키트)도 미리 생성할 수 있습니다.SDK는 API 엔드포인트를 직접 호출하지 않고 소프트웨어 패키지를 제공하여 엔드 유저와 시스템의 상호 작용을 지원합니다.이를 통해 검증 요청/응답, 오류 코드 처리 등 템플릿 작업을 절약할 수 있다.

생성된 SDK 패키지는 최종 사용자가 사용할 수 없습니다.너는 여전히 더 많은 인코딩을 해야 한다.그래도 반은 갔어.

끝!

OpenAPI 3.0 정의를 통해 API 엔지니어가 업무 논리를 완성할 때까지 기다리지 않고 API 엔드포인트를 통합할 수 있는 아날로그 서버를 만들었습니다.그들 사이의 의존이 최소화되어 팀과의 조화가 회복되었다!
API 엔지니어가 API 백엔드와 SDK를 더 빨리 만들 수 있도록 코드 사전 생성도 연구했습니다.

대단히 감사합니다

특히 에른이 내 댓글을 더 연결해줘서 고마워.아래의 작가들도 이 박문을 가능하게 했고 그들은 API를 배우는 것을 즐거움으로 만들었다.

API Design Patterns 저자: JJ Geewax

Designing APIs with Swagger and OpenAPI 조슈아 S. 포네라트와 르카스 L. 로젠스토크

Design and Build Great Web APIs저자: 마이크 아몬슨

사진 작성자Julia Joppien가 Unsplash