htps : // 슈게 r. 이오/

소개

업무로 OpenAPI를 이용한 API 설계를 실시해, 하향식으로 API를 구현했습니다.
간단한 예를 사용하여 일련의 흐름을 소개합니다. 5분도 걸리지 않고 시도할 수 있다고 생각합니다.

개요

About Swagger Specification | Documentation | Swagger | Swagger

OpenAPI란?

OpenAPI 사양은 REST API의 API 설명 형식.
OpenAPI 파일을 사용하면, 다음과 같은 API 전체를 기술할 수 있다.
· 사용 가능한 엔드포인트(/users)
· 각 엔드 포인트에서의 조작 (GET/users, POST/users)
· 조작 파라미터 조작 당 입출력
· 인증 방법
· 연락처, 라이센스, 이용 약관 및 기타 정보

API 사양은 YAML 또는 JSON으로 작성할 수 있습니다.

Swagger란?

Swagger는 OpenAPI 사양을 기반으로 구축된 일련의 오픈 소스 도구입니다.
주요 Swagger 도구는 아래.


도구
개요


Swagger Editor
OpenAPI의 사양을 기술할 수 있는 브라우저 베이스의 에디터. 이미지의 왼쪽 절반.

Swagger UI
OpenAPI 사양을 동적 API 문서로 렌더링하는 도구. 이미지의 오른쪽 절반.

Swagger Codegen
OpenAPI 사양에서 서버 스텁과 클라이언트 라이브러리를 생성합니다. 이미지 상단의 Generate Server 및 Generate Client.



아래 URL을 클릭하면 이미지와 같은 화면이 표시됩니다. 기본적으로 애완 동물 상점의 예가 표시되는 것 같습니다.
htps : // 에아와 r. 슈게 r. 이오/

OpenAPI 문서 작성 ~ API 구현

위의 Swagger 도구를 사용하여 간단한 API를 구현합니다.
이번에 구현하는 것은 매개 변수에 이름을 넣고 GET 요청하면 인사를 반환하는 API입니다.

API 문서 만들기(Swagger Editor)

Swagger Editor을 사용하여 OpenAPI (Swagger3.0) 사양으로 문서를 만듭니다.
시험만 하기 때문에 최소한의 정보를 기재하고 있습니다.

File > Save as YAML : YAML 형식으로 저장File > Convert and save as YAML : JSON 형식으로 저장

hello.yaml

openapi: 3.0.2
info:
  description: ユーザ名を与えると挨拶を返してくれるAPI
  version: 1.0.0
  title: Hello
tags:
  - name: hello
    description: ユーザに挨拶を返すAPI
paths:
  /hello:
    get:
      tags:
        - hello
      description: ユーザに挨拶する。
      operationId: getHello
      parameters:
        - name: userName
          in: query
          description: ユーザ名
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  HelloUser:
                    type: string
                    example: Hello, userName
        "400":
          description: Bad Request
        "500":
          description: Internal Server Error

코드 자동 생성(Swagger Codegen)

Genarate Server를 클릭하면 다음과 같이 생성 할 수있는 서버 측 코드 목록이 표시됩니다.
이번에는 python-flask를 선택합니다.

python-flask-server-generated라는 코드가 생성됩니다.

로직 구현

로직을 구현한다고 해도, 자동 생성된 코드를 1행 바꾸는 것 뿐입니다.

python-flask-server-generated/swagger_server/controllers/hello_user_controller.py

import connexion
import six

from swagger_server.models.inline_response200 import InlineResponse200  # noqa: E501
from swagger_server import util


def get_hello_user(user_name):  # noqa: E501
    """get_hello_user

    ユーザに挨拶する。 # noqa: E501

    :param user_name: ユーザ名
    :type user_name: str

    :rtype: InlineResponse200
    """
    return 'Hello, ' + user_name  # 変更箇所

API 동작 확인

· 웹 서버 시작

$ python3 -m swagger_server

· curl에서 API를 두드려보십시오

$ curl -X GET "http://0.0.0.0:8080/hello?userName=Yusaku"
"Hello,Yusaku"

· 브라우저에서 API를 두드려보십시오
h tp://0.0.0.0:8080/헤? 우세 r name = 유사쿠

인사가 돌아왔다.

참고

Swagger로 RESTful API 관리를 간소화
OpenAPI (Swagger) 초입문
Flask 시작하기 — Flask Handson 1 documentation