개요
- API 명세서를 작성해봅시다.
API 명세 가이드라인(From ChatGPT)
-
API 개요: API를 간단하게 설명하는 섹션입니다. API가 어떤 용도로 만들어졌는지, 어떤 유형의 API인지, 어떤 요청 방식을 사용하는지 등을 설명합니다.
-
엔드포인트(endpoint) 설명: API에 대한 각 엔드포인트에 대한 설명을 포함합니다. 각 엔드포인트는 API의 특정 동작을 수행하며, 일반적으로 HTTP 메소드(GET, POST, PUT, DELETE 등)를 사용하여 호출됩니다. 각 엔드포인트의 URL과 함께 해당 엔드포인트에서 수행되는 동작을 설명합니다.
-
매개변수(Parameter)와 요청 바디(Request Body) 설명: API 호출 시 전달되는 매개변수와 요청 바디에 대한 설명을 포함합니다. 각 매개변수에 대한 설명, 데이터 타입, 기본값 등을 명시합니다.
-
응답(Response) 설명: API의 응답에 대한 설명을 포함합니다. 응답 코드와 함께 예상되는 응답 데이터에 대한 정보를 제공합니다.
-
예제(API examples): 각 API 호출에 대한 예제를 제공합니다. 이 예제는 API 사용자가 API 호출을 어떻게 수행해야 하는지를 이해하는 데 도움이 됩니다.
-
에러(Error) 처리 설명: API 호출 중 발생할 수 있는 예외나 오류에 대한 처리 방법을 설명합니다.
-
인증(Authentication)과 권한 부여(Authorization) 설명: API에 대한 인증 및 권한 부여 방법을 설명합니다.
-
자원(Resource) 모델 설명: API가 사용하는 자원 모델에 대한 설명을 제공합니다. 이 섹션에서는 각 자원이 어떻게 표현되는지, 자원에 대한 식별자는 무엇인지, 자원의 상태와 상태 전이에 대한 정보를 제공합니다.
API 명세 예제
Posts API
포스트 목록 조회, 포스트 조회, 포스트 작성, 포스트 업데이트, 포스트 삭제 기능을 제공합니다.
| 구분 | API 명 | 설명 |
|---|---|---|
| 정보 조회 | 포스트 목록 조회 | 포스트 목록을 조회합니다. |
| 정보 조회 | 포스트 조회 | 개별 포스트를 조회합니다. |
| 정보 생성 | 포스트 생성 | 포스트를 생성합니다. |
| 정보 업데이트 | 포스트 업데이트 | 포스트를 업데이틀합니다. |
| 정보 삭제 | 포스트 삭제 | 포스트를 삭제합니다. |
포스트 생성
포스트를 생성합니다.
Request
Request Syntax
curl -X POST https://{SERVER_URL}/api/posts \
-H "Authorization: Bearer {API_KEY}" \
-H "Content-Type: application/json" \
-d '{ \
"title": "제목", \
"content": "내용" \
}'| 메서드 | 요청 URL |
|---|---|
| POST | http://{SERVER_URL}/api/posts |
Request Header
| 파라미터 | 타입 | 필수여부 | 설명 |
|---|---|---|---|
| Authorization | String | 필수 | 인증 키 |
| Content-Type | String | 필수 | application/json |
Request Elements
| 파라미터 | 타입 | 필수여부 | 설명 |
|---|---|---|---|
| title | String | 필수 | 제목 |
| content | String | 필수 | 내용 |
Response
Response Syntax
{
"id" : 1
}Response Elements
| 필드 | 타입 | 필수여부 | 설명 |
|---|---|---|---|
| id | Integer | 필수 | 포스트 고유 번호 |
포스트 목록 조회
포스트 목록을 조회합니다.
Request
Request Syntax
curl -X GET https://{SERVER_URL}/api/posts?page=1&size=10 \
-H "Authorization: Bearer {API_KEY}"| 메서드 | 요청 URL |
|---|---|
| GET | http://{SERVER_URL}/api/posts |
Request Header
| 파라미터 | 타입 | 필수여부 | 설명 |
|---|---|---|---|
| Authorization | String | 필수 | 인증 키 |
Request Elements
| 파라미터 | 타입 | 필수여부 | 설명 |
|---|---|---|---|
| page | Integer | 선택 | 페이지 번호 |
| size | Integer | 선택 | 한 페이지에 표시할 포스트 개수 |
Response
Response Syntax
{
"page": 1,
"size": 10,
"totalPage": 150,
"totalCount": 1496,
"data": [
{
"id": 1,
"title": "제목1",
"content": "내용1",
},
{
"id": 2,
"title": "제목2",
"content": "내용2",
},
{
"id": 3,
"title": "제목3",
"content": "내용3",
}
]
}Response Elements
| 필드 | 타입 | 필수여부 | 설명 |
|---|---|---|---|
| page | Integer | 필수 | 페이지 번호 |
| size | Integer | 필수 | 한 페이지에 표시할 포스트 개수 |
| totalPage | Integer | 필수 | 전체 페이지 |
| totalCount | Integer | 필수 | 전체 포스트 |
| data | Integer | 필수 | 포스트 목록 |
| id | Integer | 필수 | 포스트 고유 번호 |
| title | Integer | 필수 | 포스트 제목 |
| content | Integer | 필수 | 포스트 내용 |
