SpringBoot Server/API

PostMan, Swagger로 API 명세서 확인하기

ssury94 2025. 3. 7. 17:08

API 명세서는 애플리케이션 프로그래밍 인터페이스(API)의 사용 방법, 요청/응답 형식, 엔드포인트 등을 설명하는 문서입니다.

API 명세서는 개발자가 다른 시스템이나 애플리케이션과 통신할 때 API를 어떻게 호출하고 데이터를 주고받을지 정의합니다.

API 명세서는 클라이언트와 서버 간의 상호작용을 명확하게 정의하여, 개발자들이 API를 일관되게 사용할 수 있도록 돕습니다.

API 명세서를 잘 작성해두면 팀 간의 협업이 원활해지고, 자동화된 문서화 및 테스트가 가능해집니다.

API 명세서의 주요 내용:

  1. 기본 정보:
    • API 버전: API가 여러 버전으로 제공될 수 있기 때문에 버전 정보를 명시합니다.
    • Base URL: API 호출의 기본 URL을 정의합니다. 예: https://api.example.com/v1/
  2. 엔드포인트(Endpoints):
    • 각 API가 제공하는 URL 경로와 그 경로에 해당하는 HTTP 메서드(GET, POST, PUT, DELETE 등)를 명시합니다.
    • 예를 들어, /users 엔드포인트는 사용자 목록을 반환하는 GET 요청일 수 있습니다.
  3. 요청(Request) 파라미터:
    • API 호출 시 클라이언트가 전달해야 하는 요청 파라미터를 정의합니다.
    • 파라미터는 URL 경로, 쿼리 스트링, 헤더, 또는 요청 본문에 포함될 수 있습니다.
    • 예시: GET /users/{id}에서 id는 URL 파라미터입니다.
  4. 응답(Response):
    • 서버가 클라이언트의 요청에 대해 반환하는 응답 형식을 정의합니다.
    • 응답에는 상태 코드, 헤더, 본문 등이 포함됩니다.
    • 예를 들어, 로그인 성공 시 200 상태 코드와 함께 사용자 정보를 반환할 수 있습니다.
  5. 상태 코드(Status Codes):
    • HTTP 상태 코드를 통해 요청의 성공 여부를 알려줍니다.
      • 200 OK: 성공적인 요청
      • 201 Created: 리소스 생성 성공
      • 400 Bad Request: 잘못된 요청
      • 401 Unauthorized: 인증 실패
      • 404 Not Found: 리소스를 찾을 수 없음
      • 500 Internal Server Error: 서버 오류
  6. 예시 요청과 응답:
    • 각 API 엔드포인트에 대한 예시 요청과 응답을 명시하여 개발자가 어떤 데이터를 보내고 받을지 쉽게 이해할 수 있도록 합니다.
    • 예시: POST /login 요청에 대한 예시 JSON 데이터 및 응답 본문을 포함할 수 있습니다.
  7. 인증(Authentication):
    • API 호출 시 인증 방식을 정의합니다. 예를 들어, API 키, OAuth, JWT 등의 인증 방식이 있을 수 있습니다.
  8. 오류 코드(Error Codes):
    • API 요청에서 발생할 수 있는 오류에 대해 설명하고, 각 오류에 대한 상태 코드 및 메시지를 정의합니다.

 

PostMan에서 만들기

 

 

View complete documentation > Publish 하면 API 명세서를 작성 할 수 있습니다.

https://documenter.getpostman.com/view/40504634/2sAYdmn8tf

 

메모 API

 

documenter.getpostman.com

 

 

 

 

Swagger 라이브러리를 이용해 만들기

 

application.yml에 설정 추가

springdoc:
  api-docs:
    path: /api-docs
  swagger-ui:
    path: /swagger-ui.html

 

 

pom.xml에 디펜던시 추가

<!-- Swagger API 명세서 -->
<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
    <version>2.4.0</version>
</dependency>
<!-- Swagger API 명세서 -->

 

 

아래 주소 접속시

Cotroller에 작성한 API들을 확인 가능합니다.

 

 

http://localhost:8080/swagger-ui/index.html#/user-controller/login

http://localhost:8080/swagger-ui/index.html#/user-controller/login