OpenAPI 규범 에 기반 한 API 문서 입 니 다.swagger 소개.
482873 단어 [구조 및 디자인 모델]
집필 목적
이 글 은 Swagger 를 사용 하여 API 문 서 를 작성 하 는 방법 을 소개 합 니 다.본문 을 읽 으 면 다음 과 같이 할 수 있다.
1.1 Swagger
The World's Most Popular Framework for APIs.
2016 년 1 월 1 일부 터 Swagger Specification 이 OAI (Open API Initiative) 에 기증 (기부) 되 었 으 며 OpenAPI Specification 의 기초 가 되 었 습 니 다.
Swagger (스타킹 형) 가 첫 인상 을 준 것 은 [가장 (hen) 흐름 (niu) 행 (bai)] 입 니 다. Swagger 를 모 르 면 저 희 는 아웃 입 니 다. 공식 사 이 트 는?http://swagger.io/。
Swagger 는 간단 하지만 강력 한 기능 을 가 진 API 표현 도구 입 니 다. 지구 상에 서 가장 큰 API 도구 생태 계 를 가지 고 있 으 며 수천 명의 개발 자 들 이 거의 모든 현대 프로 그래 밍 언어 를 사용 하여 Swagger 를 지원 하고 사용 하고 있 습 니 다. Swagger 를 사용 하여 API 를 생 성하 면 대화 형 문서, 코드 를 자동 으로 생 성 하 는 SDK, API 의 발견 특성 등 을 얻 을 수 있 습 니 다.
현재 Swagger 는 Apigee, Getty 이미지, Intuit, Livingsocial, McKesson, 마이크로소프트, Morningstar, PayPal 등 세계 유명 기업 들 이 RESTful API 를 기반 으로 완벽 한 서비스 시스템 을 구축 하 는 데 도움 을 주 었 다.
2.0 버 전이 발표 되 었 습 니 다. Swagger 는 더욱 강해 졌 습 니 다. 고 맙 게 도 Swagger 의 소스 코드 는 100% github 에서 시 작 됩 니 다.
1.2 OpenAPI 규범
OpenAPI 규범 은 Linux 재단 의 프로젝트 로 API 형식 이나 API 정 의 를 설명 하 는 언어 를 정의 함으로써 RESTful 서비스 개발 과정 을 규범화 시 키 려 고 합 니 다. OpenAPI 규범 은 API 의 기본 정 보 를 설명 하 는 데 도움 을 줍 니 다. 예 를 들 어:
1.3 OpenAPI 규범 을 왜 사용 합 니까?
1.4 API 문 서 를 어떻게 작성 합 니까?
1.4.1 언어: JSON vs YAML
우 리 는 JSON 이나 YAML 의 언어 형식 을 사용 하여 API 문 서 를 작성 할 수 있 습 니 다. 그러나 개인 적 으로 YAML 을 사용 하 는 것 을 권장 합 니 다. 그 이 유 는 더 간단 하기 때 문 입 니 다. 그림 이 천 마디 를 이 길 수 있 습 니 다. 먼저 JSON 으로 쓴 문 서 를 보십시오.
-
{
-
"swagger":
"2.0",
-
"info": {
-
"version":
"1.0.0",
-
"title":
"Simple API",
-
"description":
"A simple API to learn how to write OpenAPI Specification"
-
},
-
"schemes": [
-
"https"
-
],
-
"host":
"simple.api",
-
"basePath":
"/openapi101",
-
"paths": {
-
"/persons": {
-
"get": {
-
"summary":
"Gets some persons",
-
"description":
"Returns a list containing all persons.",
-
"responses": {
-
"200": {
-
"description":
"A list of Person",
-
"schema": {
-
"type":
"array",
-
"items": {
-
"properties": {
-
"firstName": {
-
"type":
"string"
-
},
-
"lastName": {
-
"type":
"string"
-
},
-
"username": {
-
"type":
"string"
-
}
-
}
-
}
-
}
-
}
-
}
-
}
-
}
-
}
-
}
API YAML ：
-
swagger:
"2.0"
-
-
info:
-
version:
1.0
.0
-
title: Simple API
-
description: A simple API
to learn how
to write OpenAPI Specification
-
-
schemes:
-
- https
-
host: simple.api
-
basePath: /openapi101
-
-
paths:
-
/persons:
-
get:
-
summary: Gets some persons
-
description: Returns a list containing all persons.
-
responses:
-
200:
-
description: A list of Person
-
schema:
-
type:
array
-
items:
-
required:
-
- username
-
properties:
-
firstName:
-
type:
string
-
lastName:
-
type:
string
-
username:
-
type:
string
， YAML 。 ， ：
- OpenAPI YAML
- YAML-JSON
， 。（ YAML 。 YAML。）
1.4.2
API ， 。 。 ， 。 ， Swagger Editor， 、 、 ， 。
API ， 。 ：
， ， Swagger .md Swagger Editor 。
2
API ， API （ API ， “ ”） HTTP 、 ， ， HTTP 。
2.1
（ ） API ：
-
swagger:
"2.0"
-
-
info:
-
version:
1.0
.0
-
title: Simple API
-
description: A simple API
to learn how
to write OpenAPI Specification
-
-
schemes:
-
- https
-
host: simple.api
-
basePath: /openapi101
-
-
paths: {}
， 。
2.1.1 OpenAPI
swagger 속성 으로 OpenAPI 규범 의 버 전 을 설명 합 니 다.
swagger: "2.0"
， swagger， ，OpenAPI Swagger ， ， 。 ， 2.0。
2.1.2 API
API ， API （ ）、API 。
-
info:
-
version:
1.0.
0
-
title: Simple API
-
description: A simple API
to learn how
to
write OpenAPI Specification
2.1.3 API URL
web API， URL 프로 토 콜 (http 또는 https), 호스트 이름, 루트 경로 로 설명 할 수 있 습 니 다.
-
schemes:
-
- https
-
host: simple.api
-
basePath: /openapi101
， https://simple.api/open101 루트 노드 로 각종 API 를 방문 합 니 다. 구체 적 인 환경 과 관련 이 있 고 API 가 설명 하 는 근본 적 인 내용 과 관련 이 없 기 때문에 이 부분 정 보 는 선택 할 수 있 습 니 다.
2.1.4 API 의 조작 (operation)
이 예 에서 우 리 는 API 동작 을 쓰 지 않 고 YAML 의 빈 대상 {} 으로 먼저 자 리 를 차지 합 니 다.
2.2 API 작업 정의
사용자 정 보 를 보 여 주 려 면 다음 과 같이 설명 할 수 있 습 니 다.
-
swagger:
"2.0"
-
-
info:
-
version:
1.0
.0
-
title: Simple API
-
description: A simple API
to learn how
to write OpenAPI Specification
-
-
schemes:
-
- https
-
host: simple.api
-
basePath: /openapi101
-
-
paths:
-
/persons:
-
get:
-
summary: Gets some persons
-
description: Returns a list containing all persons.
-
responses:
-
200:
-
description: A list of Person
-
schema:
-
type:
array
-
items:
-
required:
-
- username
-
properties:
-
firstName:
-
type:
string
-
lastName:
-
type:
string
-
username:
-
type:
string
2.2.1 （path）
저 희 는 사용자 정 보 를 방문 하기 위해 /persons 을 추가 합 니 다.
-
paths:
-
/persons:
2.2.2 HTTP
에서 우 리 는 필요 한 자원 을 조작 하기 위해 임의의 HTTP 동 사 를 추가 할 수 있다.
예 를 들 어 사용자 정 보 를 보 여 줘 야 한다. 우 리 는 /persons 경로 에 get 방법 을 추가 할 수 있 고 간단 한 설명 정보 (summary) 를 작성 하거나 이 방법 을 설명 하 는 긴 사설 (description) 도 작성 할 수 있다.
-
get:
-
summary: Gets some persons
-
description: Returns a list containing all persons.
， get https://simple.api/open101/persons 。
2.2.3 (response) 유형
모든 방법 (또는 조작) 에 대해 우 리 는 (responses) 에 임의의 HTTP 상태 코드 (예 를 들 어 200 OK) 를 추가 할 수 있다. 혹은 404 Not Found 등). 이 예 에서 우 리 는 200 의 응답 을 추가 합 니 다.
-
responses:
-
200:
-
description: A list
of Person
2.2.4
get /persons ， (schema) 속성 으로 구체 적 인 반환 내용 을 설명 합 니 다.
한 그룹의 사용자 정 보 는 하나의 사용자 정보 대상 (array) 이 고 모든 배열 요 소 는 하나의 사용자 정보 (object) 이다. 이 대상 은 세 개의 string 유형의 속성 을 포함한다. , , 그 중에서 은 반드시 제공 해 야 한다 (required).
-
schema:
-
type:
array
-
items:
-
required:
-
- username
-
properties:
-
firstName:
-
type:
string
-
lastName:
-
type:
string
-
username:
-
type:
string
2.3 （query parameters）
사용자 가 너무 많아 서 우 리 는 한꺼번에 출력 하고 싶 지 않다. 이 럴 때 페이지 출력 은 좋 은 선택 이다. 우 리 는 요청 파 라 메 터 를 추가 해서 실현 할 수 있다.
-
swagger:
"2.0"
-
-
info:
-
version:
1.0
.0
-
title: Simple API
-
description: A simple API
to learn how
to write OpenAPI Specification
-
-
schemes:
-
- https
-
host: simple.api
-
basePath: /openapi101
-
-
paths:
-
/persons:
-
get:
-
summary: Gets some persons
-
description: Returns a list containing all persons. The list supports paging.
-
#START############################################################################
-
parameters:
-
- name: pageSize
-
in: query
-
description: Number
of persons returned
-
type:
integer
-
- name: pageNumber
-
in: query
-
description: Page number
-
type:
integer
-
# END ############################################################################
-
responses:
-
200:
-
description: A list
of Person
-
schema:
-
type: array
-
items:
-
required:
-
- username
-
properties:
-
firstName:
-
type:
string
-
lastName:
-
type:
string
-
username:
-
type:
string
2.3.1 get
get 속성:
-
paths:
-
/persons:
-
get:
-
summary: Gets some persons
-
description: Returns a
list containing all persons. The
list supports paging.
-
#START############################################################################
-
parameters:
-
# END ############################################################################
2.3.2
， （name） pageSize 와 pageNumber 의 정형 (integer) 매개 변 수 를 간단하게 설명 한다.
-
parameters:
-
#START############################################################################
-
-
name: pageSize
-
in: query
-
description: Number
of persons returned
-
type: integer
-
-
name: pageNumber
-
in: query
-
description: Page number
-
type: integer
-
#
END ##############################################################################
-
responses:
， get /persons?pageSize=20&pageNumber=2 2 （ 20 ） 。
2.4 （path parameter）
때때로 우 리 는 사용자 이름 에 따라 사용자 정 보 를 찾 으 려 고 할 때, 예 를 들 어 유사 한 인 터 페 이 스 를 추가 할 수 있 는 인터페이스 조작 을 추가 해 야 한다. /persons/{username} 사용자 정 보 를 가 져 오 는 동작 입 니 다. 주의, {username} 요청 경로 에 있 는 인자 입 니 다.
-
swagger:
"2.0"
-
-
info:
-
version:
1.0
.0
-
title: Simple API
-
description: A simple API
to learn how
to write OpenAPI Specification
-
-
schemes:
-
- https
-
host: simple.api
-
basePath: /openapi101
-
-
paths:
-
/persons:
-
get:
-
summary: Gets some persons
-
description: Returns a list containing all persons. The list supports paging.
-
parameters:
-
- name: pageSize
-
in: query
-
description: Number of persons returned
-
type: integer
-
- name: pageNumber
-
in: query
-
description: Page number
-
type: integer
-
responses:
-
200:
-
description: A list of Person
-
schema:
-
type:
array
-
items:
-
required:
-
- username
-
properties:
-
firstName:
-
type:
string
-
lastName:
-
type:
string
-
username:
-
type:
string
-
-
#START############################################################################
-
/persons/{username}:
-
get:
-
summary: Gets a person
-
description: Returns a single person
for its username
-
parameters:
-
- name: username
-
in: path
-
required:
true
-
description: The person
's username
-
type:
string
-
responses:
-
200:
-
description: A Person
-
schema:
-
required:
-
- username
-
properties:
-
firstName:
-
type:
string
-
lastName:
-
type:
string
-
username:
-
type:
string
-
404:
-
description: The Person does
not exists.
-
#
END ############################################################################
2.4.1 get /persons/{username}
/persons ， /persons/{username} ， get （ ） 。
-
swagger:
"2.0"
-
-
info:
-
version:
1.0
.0
-
title: Simple API
-
description: A simple API
to learn how
to write OpenAPI Specification
-
-
schemes:
-
- https
-
host: simple.api
-
basePath: /openapi101
-
-
paths:
-
/persons:
-
username:
-
type:
string
-
#START############################################################################
-
/persons/{username}:
-
get:
-
summary: Gets a person
-
description: Returns a single person
for its username
-
# END ############################################################################
2.4.2 username
{username} ， parameters ， （ { } ） 。 in 이 속성 은 경로 (path) 인자 임 을 표시 합 니 다.
-
parameters:
-
- name: username
-
in: path
-
required:
true
-
description: The person
's username
-
type:
string
：required: true, Swagger 의 자동 완성 기능 에는 이 속성 정의 가 포함 되 어 있 지 않 습 니 다. 쓰 지 않 았 다 면. require 속성 false username 매개 변 수 를 선택 할 수 있 습 니 다. 그러나 사실상 경로 매개 변수 로 서 필요 합 니 다.
2.4.3 정의 응답 메시지
단일 사용자 정 보 를 얻 는 데 도 작성 해 야 한 다 는 것 을 잊 지 마 세 요. 200 응답 메시지, 응답 메시지 의 내용 은 이전에 설명 한 사용자 정보 (사용자 정보 목록 의 요소) 입 니 다.
-
responses:
-
200:
-
description: A Person
-
schema:
-
required:
-
- username
-
properties:
-
firstName:
-
type:
string
-
lastName:
-
type:
string
-
username:
-
type:
string
，API username ， ， 404 。 404 ：
-
404:
-
description: The Person does
not exists.
2.5 （body parameter）
사용자 정 보 를 추가 해 야 할 때 제공 할 수 있 는 것 이 필요 합 니 다. post /persons 라 는 API 조작 을 했다.
-
swagger:
"2.0"
-
-
info:
-
version:
1.0
.0
-
title: Simple API
-
description: A simple API
to learn how
to write OpenAPI Specification
-
-
schemes:
-
- https
-
host: simple.api
-
basePath: /openapi101
-
-
paths:
-
/persons:
-
get:
-
summary: Gets some persons
-
description: Returns a list containing all persons. The list supports paging.
-
parameters:
-
- name: pageSize
-
in: query
-
description: Number of persons returned
-
type: integer
-
- name: pageNumber
-
in: query
-
description: Page number
-
type: integer
-
responses:
-
200:
-
description: A list of Person
-
schema:
-
type:
array
-
items:
-
required:
-
- username
-
properties:
-
firstName:
-
type:
string
-
lastName:
-
type:
string
-
username:
-
type:
string
-
#START############################################################################
-
post:
-
summary: Creates a person
-
description: Adds a
new person
to the persons list.
-
parameters:
-
- name: person
-
in: body
-
description: The person
to create.
-
schema:
-
required:
-
- username
-
properties:
-
firstName:
-
type:
string
-
lastName:
-
type:
string
-
username:
-
type:
string
-
responses:
-
204:
-
description: Persons succesfully created.
-
400:
-
description: Persons couldn
't have been created.
-
#
END ############################################################################
-
/persons/{username}:
-
get:
-
summary: Gets a person
-
description: Returns a single person
for its username.
-
parameters:
-
- name: username
-
in: path
-
required:
true
-
description: The person
's username
-
type:
string
-
responses:
-
200:
-
description: A Person
-
schema:
-
required:
-
- username
-
properties:
-
firstName:
-
type:
string
-
lastName:
-
type:
string
-
username:
-
type:
string
-
404:
-
description: The Person does
not exists.
2.5.1 post /persons
/persons post ：
-
paths:
-
/persons:
-
post:
-
summary: Creates a person
-
description: Adds a
new person
to the persons list.
2.5.2
post ， in 속성 명시 적 설명 매개 변 수 는? body 매개 변수 정의 참조 get /persons/{username} 의 200 응답 메시지 체 파라미터, 즉 사용자 의 성, 이름, 사용자 이름 을 포함 합 니 다.
-
parameters:
-
-
name: person
-
in: body
-
description: The person
to create.
-
schema:
-
required:
-
- username
-
properties:
-
firstName:
-
type:
string
-
lastName:
-
type:
string
-
username:
-
type:
string
2.5.3
post 。
-
responses:
-
204:
-
description: Persons succesfully created.
-
400:
-
description: Persons couldn
't have been created.
3
API 。 ， ， “ ”。 （definitions） API 。
3.1
2 API ， Person ， DRY ☹。
-
swagger:
"2.0"
-
-
info:
-
version:
1.0
.0
-
title: Simple API
-
description: A simple API
to learn how
to write OpenAPI Specification
-
-
schemes:
-
- https
-
host: simple.api
-
basePath: /openapi101
-
-
paths:
-
/persons:
-
get:
-
summary: Gets some persons
-
description: Returns a list containing all persons. The list supports paging.
-
parameters:
-
- name: pageSize
-
in: query
-
description: Number of persons returned
-
type: integer
-
- name: pageNumber
-
in: query
-
description: Page number
-
type: integer
-
responses:
-
200:
-
description: A list of Person
-
schema:
-
type:
array
-
items:
-
#START
1 ###################################################################
-
required:
-
- username
-
properties:
-
firstName:
-
type:
string
-
lastName:
-
type:
string
-
username:
-
type:
string
-
#
END
1 ###################################################################
-
post:
-
summary: Creates a person
-
description: Adds a
new person
to the persons list.
-
parameters:
-
- name: person
-
in: body
-
description: The person
to create.
-
schema:
-
#START
2 ###################################################################
-
required:
-
- username
-
properties:
-
firstName:
-
type:
string
-
lastName:
-
type:
string
-
username:
-
type:
string
-
#
END
2 ###################################################################
-
responses:
-
204:
-
description: Persons succesfully created.
-
400:
-
description: Persons couldn
't have been created.
-
/persons/{username}:
-
get:
-
summary: Gets a person
-
description: Returns a single person
for its username.
-
parameters:
-
- name: username
-
in: path
-
required:
true
-
description: The person
's username
-
type:
string
-
responses:
-
200:
-
description: A Person
-
schema:
-
#START
3 ###################################################################
-
required:
-
- username
-
properties:
-
firstName:
-
type:
string
-
lastName:
-
type:
string
-
username:
-
type:
string
-
#
END
3 ###################################################################
-
404:
-
description: The Person does
not exists.
， (definition) 이 문 서 를 재 구성 합 니 다:
-
swagger:
"2.0"
-
-
info:
-
version: 1.0.0
-
title: Simple API
-
description: A simple API to learn how to write OpenAPI Specification
-
-
schemes:
-
- https
-
host: simple.api
-
basePath: /openapi101
-
-
paths:
-
/persons:
-
get:
-
summary: Gets some persons
-
description: Returns a list containing all persons. The list supports paging.
-
parameters:
-
- name: pageSize
-
in: query
-
description: Number of persons returned
-
type:
integer
-
- name: pageNumber
-
in: query
-
description: Page number
-
type:
integer
-
responses:
-
200:
-
description: A list of Person
-
schema:
-
#START############################################################################
-
$ref:
"#/definitions/Persons"
-
# END ############################################################################
-
post:
-
summary: Creates a person
-
description: Adds a new person to the persons list.
-
parameters:
-
- name: person
-
in: body
-
description: The person to create.
-
schema:
-
#START############################################################################
-
$ref:
"#/definitions/Person"
-
# END ############################################################################
-
responses:
-
204:
-
description: Persons succesfully created.
-
400:
-
description: Persons couldn
't have been created.
-
/persons/{username}:
-
get:
-
summary: Gets a person
-
description: Returns a single person for its username.
-
parameters:
-
- name: username
-
in: path
-
required: true
-
description: The person's username
-
type: string
-
responses:
-
200:
-
description: A Person
-
schema:
-
#START############################################################################
-
$ref:
"#/definitions/Person"
-
# END ############################################################################
-
404:
-
description: The Person does not exists.
-
-
#START ####################################################################
-
definitions:
-
Person:
-
required:
-
- username
-
properties:
-
firstName:
-
type: string
-
lastName:
-
type: string
-
username:
-
type: string
-
Persons:
-
type: array
-
items:
-
$ref:
"#/definitions/Person"
-
# END ####################################################################
。 OpenAPI （definition） “ ， ”。
3.1.1 (definitions) 항목
우선 API 문서 의 끝 에 하 나 를 추가 합 니 다 (definitions) 항목 (사실 문서 의 임 의 위치 에 놓 을 수도 있 습 니 다. 문서 끝 에 두 는 것 이 습관 일 뿐 입 니 다):
-
404:
-
description: The Person does
not exists.
-
#START############################################################################
-
definitions:
-
# END ############################################################################
3.1.2 （ ）
그리고 저희 가 하나 더... Person 대상 의 정의:
-
definitions:
-
#START############################################################################
-
Person:
-
required:
-
- username
-
properties:
-
firstName:
-
type:
string
-
lastName:
-
type:
string
-
username:
-
type:
string
-
#
END ############################################################################
3.1.3 다른 것 정의 항목 에서, 우 리 는 방금 정 의 된 것 을 즉시 인용 할 수 있다 Person 다른 , Persons. Persons 를 추가 합 니 다. 하나 Person 대상 의 배열 입 니 다. 이전에 직접 정의 한 것 과 다른 점 은 우리 가 속성 을 추가 한 것 입 니 다. 즉, $ref 참조 Person 。
-
Persons:
-
type:
array
-
items:
-
$ref:
"#/definitions/Person"
3.1.4
일단 정의 가 되면 Person ，우 리 는 원래 응답 메시지 에 해당 하 는 정의 필드 를 교체 할 수 있다.
3.1.4.1 get/persons
원래:
-
responses:
-
200:
-
description: A list
of Person
-
schema:
-
type:
array
-
items:
-
required:
-
- username
-
properties:
-
firstName:
-
type:
string
-
lastName:
-
type:
string
：
-
responses:
-
200:
-
description: A
list of Person
-
schema:
-
$ref:
"#/definitions/Persons"
3.1.4.2 get/persons/{username}
：
-
responses:
-
200:
-
description: A Person
-
schema:
-
required:
-
- username
-
properties:
-
firstName:
-
type:
string
-
lastName:
-
type:
string
-
username:
-
type:
string
：
-
responses:
-
200:
-
description: A Person
-
schema:
-
$ref:
"#/definitions/Person"
3.1.5
메시지 에서 만 사용 할 수 있 는 것 이 아니 라 매개 변수 에서 도 사용 할 수 있 습 니 다.
3.1.5.1 post /persons
원래:
-
post:
-
summary: Creates a person
-
description: Adds a new person
to the persons list.
-
parameters:
-
-
name: person
-
in: body
-
description: The person
to create.
-
schema:
-
required:
-
- username
-
properties:
-
firstName:
-
type:
string
-
lastName:
-
type:
string
-
username:
-
type:
string
($ref) 의 역할 을 다음 에 응답 메시지 의 정의 에 사용 합 니 다.
-
post:
-
summary: Creates a person
-
description: Adds a
new person
to the persons list.
-
parameters:
-
- name: person
-
in: body
-
description: The person
to create.
-
schema:
-
$ref:
"#/definitions/Person"
：
-
swagger:
"2.0"
-
-
info:
-
version:
1.0
.0
-
title: Simple API
-
description: A simple API
to learn how
to write OpenAPI Specification
-
-
schemes:
-
- https
-
host: simple.api
-
basePath: /openapi101
-
-
paths:
-
/persons:
-
get:
-
summary: Gets some persons
-
description: Returns a list containing all persons. The list supports paging.
-
parameters:
-
- name: pageSize
-
in: query
-
description: Number of persons returned
-
type: integer
-
- name: pageNumber
-
in: query
-
description: Page number
-
type: integer
-
responses:
-
200:
-
description: A list of Person
-
schema:
-
$ref:
"#/definitions/Persons"
-
#START############################################################################
-
500:
-
$ref:
"#/responses/Standard500ErrorResponse"
-
#
END ############################################################################
-
post:
-
summary: Creates a person
-
description: Adds a
new person
to the persons list.
-
parameters:
-
- name: person
-
in: body
-
description: The person
to create.
-
schema:
-
$ref:
"#/definitions/Person"
-
responses:
-
204:
-
description: Persons succesfully created.
-
400:
-
description: Persons couldn
't have been created.
-
#START############################################################################
-
500:
-
$ref:
"#/responses/Standard500ErrorResponse"
-
#
END ############################################################################
-
-
/persons/{username}:
-
get:
-
summary: Gets a person
-
description: Returns a single person
for its username.
-
parameters:
-
- name: username
-
in: path
-
required:
true
-
description: The person
's username
-
type:
string
-
responses:
-
200:
-
description: A Person
-
schema:
-
$ref:
"#/definitions/Person"
-
404:
-
description: The Person does
not exists.
-
#START############################################################################
-
500:
-
$ref:
"#/responses/Standard500ErrorResponse"
-
#
END ############################################################################
-
-
definitions:
-
Person:
-
required:
-
- username
-
properties:
-
firstName:
-
type:
string
-
lastName:
-
type:
string
-
username:
-
type:
string
-
Persons:
-
type:
array
-
items:
-
$ref:
"#/definitions/Person"
-
#START############################################################################
-
Error:
-
properties:
-
code:
-
type:
string
-
message:
-
type:
string
-
-
responses:
-
Standard500ErrorResponse:
-
description: An unexpected
error occured.
-
schema:
-
$ref:
"#/definitions/Error"
-
#
END ############################################################################
3.2
($ref) 그래서 우 리 는 이렇게 쓸 수 있다.
-
paths:
-
/persons:
-
get:
-
summary: Gets some persons
-
description: Returns a list containing all persons. The list supports paging.
-
parameters:
-
- name: pageSize
-
in: query
-
description: Number of persons returned
-
type: integer
-
- name: pageNumber
-
in: query
-
description: Page number
-
type: integer
-
responses:
-
200:
-
description: A list of Person
-
schema:
-
$ref:
"#/definitions/Persons"
-
#START############################################################################
-
500:
-
description: An unexpected
error occured.
-
schema:
-
properties:
-
code:
-
type:
string
-
message:
-
type:
string
-
#
END ############################################################################
-
post:
-
summary: Creates a person
-
description: Adds a
new person
to the persons list.
-
parameters:
-
- name: person
-
in: body
-
description: The person
to create.
-
schema:
-
$ref:
"#/definitions/Person"
-
responses:
-
204:
-
description: Persons succesfully created.
-
400:
-
description: Persons couldn
't have been created.
-
#START############################################################################
-
500:
-
description: An unexpected
error occured.
-
schema:
-
properties:
-
code:
-
type:
string
-
message:
-
type:
string
-
#
END ############################################################################
-
-
/persons/{username}:
-
get:
-
summary: Gets a person
-
description: Returns a single person
for its username.
-
parameters:
-
- name: username
-
in: path
-
required:
true
-
description: The person
's username
-
type:
string
-
responses:
-
200:
-
description: A Person
-
schema:
-
$ref:
"#/definitions/Person"
-
404:
-
description: The Person does
not exists.
-
#START############################################################################
-
500:
-
description: An unexpected
error occured.
-
schema:
-
properties:
-
code:
-
type:
string
-
message:
-
type:
string
-
#
END ############################################################################
3.2.1 HTTP 500
HTTP 500 ， API （error code） （message） ， ：
-
definitions:
-
Person:
-
required:
-
- username
-
properties:
-
firstName:
-
type:
string
-
lastName:
-
type:
string
-
username:
-
type:
string
-
Persons:
-
type: array
-
items:
-
$ref:
"#/definitions/Person"
-
#START############################################################################
-
Error:
-
properties:
-
code:
-
type:
string
-
message:
-
type:
string
-
# END ############################################################################
3.2.2 Error
“ 、 ” ， Error ：
-
paths:
-
/persons:
-
get:
-
summary: Gets some persons
-
description: Returns a list containing all persons. The list supports paging.
-
parameters:
-
- name: pageSize
-
in: query
-
description: Number of persons returned
-
type: integer
-
- name: pageNumber
-
in: query
-
description: Page number
-
type: integer
-
responses:
-
200:
-
description: A list of Person
-
schema:
-
$ref:
"#/definitions/Persons"
-
500:
-
description: An unexpected
error occured.
-
schema:
-
#START############################################################################
-
$ref:
"#/definitions/Error"
-
#
END ############################################################################
-
post:
-
summary: Creates a person
-
description: Adds a
new person
to the persons list.
-
parameters:
-
- name: person
-
in: body
-
description: The person
to create.
-
schema:
-
$ref:
"#/definitions/Person"
-
responses:
-
204:
-
description: Persons succesfully created.
-
400:
-
description: Persons couldn
't have been created.
-
500:
-
description: An unexpected
error occured.
-
schema:
-
#START############################################################################
-
$ref:
"#/definitions/Error"
-
#
END ############################################################################
-
/persons/{username}:
-
get:
-
summary: Gets a person
-
description: Returns a single person
for its username.
-
parameters:
-
- name: username
-
in: path
-
required:
true
-
description: The person
's username
-
type:
string
-
responses:
-
200:
-
description: A Person
-
schema:
-
$ref:
"#/definitions/Person"
-
404:
-
description: The Person does
not exists.
-
500:
-
description: An unexpected
error occured.
-
schema:
-
#START############################################################################
-
$ref:
"#/definitions/Error"
-
#
END ############################################################################
($ref) 는 정 의 된 응답 메 시 지 를 사용 합 니 다. 예 를 들 어:
3.2.4.1 get /users
-
definitions:
-
Person:
-
required:
-
- username
-
properties:
-
firstName:
-
type:
string
-
lastName:
-
type:
string
-
username:
-
type:
string
-
Persons:
-
type: array
-
items:
-
$ref:
"#/definitions/Person"
-
Error:
-
properties:
-
code:
-
type:
string
-
message:
-
type:
string
-
#START############################################################################
-
responses:
-
Standard500ErrorResponse:
-
description: An unexpected error occured.
-
schema:
-
$ref:
"#/definitions/Error"
-
# END ############################################################################
3.2.3
， 。 OpenAPI responses ， ， 。
-
responses:
-
200:
-
description: A
list of Person
-
schema:
-
$ref:
"#/definitions/Persons"
-
#START############################################################################
-
500:
-
$ref:
"#/responses/Standard500ErrorResponse"
-
# END ############################################################################
： Error 。
3.2.4
3.2.4.2 post/users
-
responses:
-
204:
-
description: Persons succesfully created.
-
400:
-
description: Persons couldn
't have been created.
-
#START############################################################################
-
500:
-
$ref:
"#/responses/Standard500ErrorResponse"
-
# END ############################################################################
3.2.4.3 get/users/{username}
-
responses:
-
200:
-
description: A Person
-
schema:
-
$ref:
"#/definitions/Person"
-
404:
-
description: The Person does
not exists.
-
#START############################################################################
-
500:
-
$ref:
"#/responses/Standard500ErrorResponse"
-
# END ############################################################################
3.3
、 ， 。
-
swagger:
"2.0"
-
-
info:
-
version:
1.0
.0
-
title: Simple API
-
description: A simple API
to learn how
to write OpenAPI Specification
-
-
schemes:
-
- https
-
host: simple.api
-
basePath: /openapi101
-
-
paths:
-
/persons:
-
get:
-
summary: Gets some persons
-
description: Returns a list containing all persons. The list supports paging.
-
#START############################################################################
-
parameters:
-
- $ref:
"#/parameters/pageSize"
-
- $ref:
"#/parameters/pageNumber"
-
#
END ############################################################################
-
responses:
-
200:
-
description: A list of Person
-
schema:
-
$ref:
"#/definitions/Persons"
-
500:
-
$ref:
"#/responses/Standard500ErrorResponse"
-
post:
-
summary: Creates a person
-
description: Adds a
new person
to the persons list.
-
parameters:
-
- name: person
-
in: body
-
description: The person
to create.
-
schema:
-
좋은 웹페이지 즐겨찾기
