openapi
API 를 정의하는 방법을 설정한다. 표준이 계속적으로 업데이트 되어오다 보니 여러 버전이 있는 것으로 보인다. 이전 버전은 2 였으며, 현재는 3 이다. 전문적으로 기능들을 사용할 것이 아니기 때문에, 그냥 현재 최신인 3.0.3 으로 한다.
info
API의 정보를 입력하기 위한 항목이다. 세부적으로 title, description, version 등을 넣을 수 있다. 적절하게 설명을 넣어주면 된다.
openapi 와 info 항목을 합쳐서 metadata 라고 묶어서 얘기한다.
servers
API 서버와 기본이 되는 URL을 정의한다.
로컬에 서버가 있으면 http://localhost:8080 정도로도 충분하다. 여러 개의 서버를 입력할 수 있도록 리스트화 되어 있다. 각 리스트에 대한 아이템은 url과 description 항목을 통해서 정의할 수 있도록 되어 있다.
tags
API 를 categorize하기 위해서 사용한다. 리스트 항목을 하위로 가지며 각 아이템은 name과 description 항목을 가진다.
paths
API를 문서화하는데 핵심이 되는 부분이다.
paths 하위로 각 API 경로를 지정해서 정의하게 된다.
API 경로 아래에는 http method를 지정하고, 그 하위에 summary, description 등의 설명을 설정할 수 있는 항목이 온다.
같은 레벨에서 tags를 지정하면 API를 categorize 할 수 있다. 이 항목에 해당하는 값은 paths와 동일 레벨로 tags라는 항목으로 정의해야 한다.
oprationId 는 고유한 문자열 값을 가져야 한다. 이 값을 자동적으로 설정되지 않고 수동으로 설정할 수 있도록 해 뒀는지 이유는 아직 찾지 못했다.
parameters
API 경로 하위에 정의한다. summary, description, tags 등의 항목과 같은 레벨이다.
URL 경로, query, header, cookie 등을 통해서 요청에서 달라질 수 있는 입력 파라메터를 정의한다.
하위에는 name, in, required, description, schema 등의 항목이 올 수 있다.
in을 통해서 어떤 부분을 통해 입력 파라메터를 받는지 설정한다. 각 값은 path, query, header, cookie 가 될 수 있다.
requestbody
요청에 대한 입력값이 body를 통해서 들어올 경우에는 이 항목을 이용한다.
required, content 항목이 올 수 있다.
content 하위에는 어떤 타입의 형태로 요청이 되었는지 MIME 타입의 항목이 들어온다. 예를 들면, application/json, image, application/x-www-form-urlencoded 이 될 수 있다.
타입 하위에는 schema가 와서 json이나 form이 어떠한 구조로 되어있는지 정의할 수 있다.
responses
어떤 응답이 올 수 있는지에 대한 정의이다.
하위에는 바로 응답 코드가 오게 된다. 즉, ‘200’이나 ‘401’ 같은 항목이 온다.
응답 코드 하위에는 description 과 content가 오며, content는 requestbody에서 정의되었던 것과 동일한 형태로 정의할 수 있다.
components
앞에서 데이터 형태가 어떠한지를 정의하는 schema를 공통으로 묶어서 정의할 수 있다. 주로 가장 마지막 항목으로 나타나고, paths와 같은 레벨로 components 라는 항목을 정의한다.
components 항목 하위에 schemas라는 항목을 정의할 수 있는데, 여기에 입력과 출력에 대한 데이터 모델을 정의할 수 있다.
데이터 모델에 대한 이름 항목으로 지정할 수 있으며, 이 하위에 type, properties, required 라는 항목을 정의할 수 있다.
type에는 integer, double, string, object, array등의 값을 가질 수 있다.
type이 object 인 경우, properties 라는 하위 항목을 가질 수 있고, 이 하위에는 다시 데이터 모델에 대한 이름 항목을 반복해서 정의할 수 있다.
authentication
components의 schemas 와 같은 레벨로 securitySchemas 항목을 정의할 수 있다. 인증에 대한 설정을 할 수 있다. 하위에는 인증에 대한 이름을 지정하면 된다.
인증 이름의 하위에는 type 과 schema 항목이 올 수 있다. type으로는 http나 oauth2가 오면 되고, schma에는 인증 방식에 따라, basic, bearer, apiKey 등이 올 수 있다.
bearer인 경우에 token을 JWT를 사용하고자 할 때, bearerFormat: JWT를 설정하면 된다.
apiKey인 경우에는 in 항목이 하위에 올 수 있는데, apiKey가 넘어오는 방식에 따라 header, query, cookie를 지정해준다.
인증 방식을 각 경로마다 지정을 해줄 수 있다. api 의 요청 method 하위에 security 라는 항목을 설정할 수 있으며, 리스트 형태로 지정한다. 아이템으로 인증 이름을 지정해주면 되고, 구체적인 설정값은 알 수 없지만, 일반적으로 [] 과 같이 설정해주는 것으로 보인다.
$ref
components에서 schema를 정의해놓고, 다른 곳에서 참조해서 사용할 수 있다. 즉, paramters나 requestbody, reponses 등에서 참조해서 사용할 수 있다.
$ref:'#/components/schemas/{스키마 이름}과 같은 형태로 참조해서 사용할 수 있다. components 하위에는 여러 가지 항목을 정의할 수 있으므로, schemas만 올 수 있는 것은 아니다.
