[ Swagger ] Swagger UI를 통해 API 명세서 Postman 공유

 

1. 글을 작성한 이유

프로젝트를 하면서 API 스펙을 공유하기 위해 다양한 방법을 찾았습니다. 보통 API 문서화를 하기 위해서는 Rest DOCS와 Swagger를 통해서 API를 문서화를 했다.

저희는 Swagger를 선택을 하였고 문서화를 하였으나 문서화를 다른 사람에게 공유하기 위해서 방법을 찾던 도중에 배포를 하지 않고 Postman으로 문서 공유화가 가능하여 글을 작성을 했습니다.

 

2. Swagger UI 적용하기 

처음에 Gradle에 의존성을 추가를 합니다.

    implementation 'org.springdoc:springdoc-openapi-ui:1.6.9'

 

이후 Config작업을 합니다.

@Configuration
public class OpenApiConfig {
    @Bean
    public OpenAPI openAPI() {

        Info info = new Info()
                .version("v1.0.0")
                .title("스터디 타임 API 명세서")
                .description("StudyTime API Description");

        return new OpenAPI()
                .info(info);
    }
}

이 부분에서 버전과 title, description이 있는데 swagger에 제목과 설명을 작성하는 부분입니다. 이 경우에 사용자에 맞게 설정을 하면 됩니다.

 

이후 서버를 실행을 시킨고 다음과 같은 URL을 입력한다.

http://localhost:8080/swagger-ui/index.html

그러면 다음과 같은 화면이 나옵니다.

위 사진은 커스텀을 한 화면입니다.

위에 Config설정을 보면 Title과 Version, Description이 정확하게 변경된 화면을 확인할 수 있다.

일단 기본적으로 설정만 하였다면 밑에 API는 영어로 기본 값으로 설정이 되어있다.

그러면 커스텀하는 방법을 알아보겠습니다.

 

3. Swagger 어노테이션 설정

---

1. Tag

@Tag(name = "user", description = "사용자 API")
@RequestMapping(value = "${demo.api}/users")
@RestController
public class UserController

name: 태그의 이름

description: 태그에 대한 설명

 

2. Schema

description : 한글명
defaultValue : 기본값
allowableValues :

 

3. Operation

summary : api에 대한 간략 설명
description : api에 대한 상세 설명
responses : api Response 리스트
parameters : api 파라미터 리스트

 

4. ApiResponse

responseCode : http 상태코드
description : response에 대한 설명
content : Response payload 구조
schema : payload에서 이용하는 Schema
hidden : Schema 숨김여부
implementation : Schema 대상 클래스

 

5. Parameter

name : 파라미터 이름
description : 파라미터 설명
in : 파라미터 위치
query, header, path, cookie

 

 

 

4. Postman으로 설정하기

---

이 화면에서 API를 JSON으로 Export하는 버튼을 클린한다. 그러면 JSON으로 변환이 되는데 이걸 복사해서 Postman에 impot를 하는 방식을 사용한다.

이후 복사한 JSON파일을 붙여넣고 Public을 통해 공개적으로 설정이 가능합니다.

참고

---

[Spring Boot Tutorial] 15. Open API 3.0 + Swagger v3 상세설정

 

Swagger에서 Postman으로 Export하기 - Blog

 

[Spring Data JPA Tutorial] 14. Swagger v3 상세설정 및 request 유효성 검증