프로젝트/프로젝트 관련

Spring fox(Swagger) - API 문서화

Wonuk 2021. 12. 5. 21:42
반응형

API Docs는 왜 필요한가?

본인이 위치 서비스를 구현한다고 가정해봅시다.

그렇다면 대한민국 지도 데이터를 모두 구현해야 할 것입니다.

 

하지만 이미 잘 구현된 라이브러리가 공개되어 있다면?

즉, 네이버 지도 API 등을 사용하면 시간도 절약할 수 있고,

완성도가 높은 서비스를 나의 서비스에 적용시킬 수 있습니다.

 

API Doucuments란?

API Documents는 API 사용 방법을 사용자에게 알려주는 문서입니다.

API를 잘 사용하기 위해서는 API 문서를 잘 읽어야 합니다.

위에서 언급한 API뿐만 아니라, 외부에 공개하는 모든 API들은 Documents가 존재합니다.

  • 요청 URL
  • 해당 API에 대한 설명
  • 헤더 정보
  • 요청 파라미터
  • 응답 데이터
  • 요청 파라미터와 응답 데이터에 대한 설명
  • API 호출/응답 예제
  • 등등..

이러한 정보들을 제공해주는 문서는 잘 설명되어 있어야 사용자들이 문의 없이 API를 잘 사용할 수 있을 것입니다.

또한 MSA(마이크로 서비스 아키텍처)에서는 API로 주로 통신하기 때문에, 문서화가 잘 되어 있어야 합니다.

 

- MSA에 대한 공부는 후순위로 미루겠습니다.

 

Swagger란

API docs는 이처럼 중요하지만, API 스펙을 문서로 관리한다는 것은 쉽지가 않습니다.

특히, 개인 프로젝트라면 시간이 많이 소요됩니다.

이러한 작업을 자동화 시켜주는 라이브러리가 Spring fox(Swagger) 입니다.

 

Sprinboot에서 Swagger를 사용하면, 컨트롤러에 명시된 어노테이션을 해석하여 API 문서를 자동으로 만들어줍니다.

또한 Swagger에서 만들어주는 docs 페이지에서 테스트까지 할 수 있습니다.

 

참고로 Swagger는 Java에 종속된 라이브러리가 아니고 언어마다 다양한 에코시스템 프로젝트가 있습니다.

[참고자료] https://swagger.io/tools/open-source/open-source-integrations/

 

swagger는 OpenAPI 스펙을 기준으로 문서화 하여 HTML 페이지를 자동으로 만들어주는 오픈소스 프레임워크 입니다.

RESTful API 설계 및 문서화하여 공유가 필요할 때(협업에서 활용가능) 자주 사용된다는 것을 알 수 있습니다.

 API Path 와 Request, Response 값 및 제약 등을 한번에 알려줄 수 있습니다.

자세한 내용은 springfox document 홈페이지에서도 확인이 가능하다.

 

OpenAPI 와 Swagger의 관계

OpenAPI는 RESTful API 설계를 위한 업계 표준 사양을 나타내고 Swagger는 SmartBear 도구 세트를 나타냅니다

요약하면 Swagger 는 이제 OpenAPI 사양을 구현하기 위한 도구 세트 (Swagger Editor, Swagger UI, SwaggerHub) 가 되었으며, 브랜드명만 변경하지 않은 채 그대로 사용하기로 했습니다.

참고 Swagger 공식 블로그 포스팅 https://swagger.io/blog/api-strategy/difference-between-swagger-and-openapi/

 

사용방법 Swagger 3.0

 

1. 의존성 추가

 

build.gradle

/* build.gradle */

dependencies {
    // ..
    implementation 'io.springfox:springfox-boot-starter:3.0.0'
    // ..
}

 

2. Config 설정파일 추가

@Configuration
public class SwaggerConfig {

    @Bean
    public Docket api() {
        return new Docket(DocumentationType.OAS_30)
                .useDefaultResponseMessages(false)
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.example.springfox.controller"))
                .paths(PathSelectors.any())
                .build()
                .apiInfo(apiInfo());
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("Swagger")
                .description("swagger config")
                .version("1.0")
                .build();
    }
}
  • Docket : Swagger 설정의 핵심이 되는 Bean
  • useDefaultResponseMessages : Swagger 에서 제공해주는 기본 응답 코드                                                    (200, 401, 403, 404). false 로 설정하면 기본 응답 코드를 노출하지 않음
  • apis : api 스펙이 작성되어 있는 패키지 (Controller) 를 지정
  • paths : apis 에 있는 API 중 특정 path 를 선택
  • apiInfo : Swagger UI 로 노출할 정보

 

RequestHandlerSelectors.basePackage("com.example.springfox.controller") 

 

사용시 주의사항

로컬 실행 후 URL 접속하면 되는데 Swagger 2.x 버전과 다릅니다.

 

실제 제 프로젝트에 Swagger를 구현하였으니

실제 사용 예제를 보고싶으시다면 아래의 깃허브 링크로 방문해주세요

https://github.com/Hwangwonuk/cucumber-market

 

GitHub - Hwangwonuk/cucumber-market: 개인 프로젝트

개인 프로젝트. Contribute to Hwangwonuk/cucumber-market development by creating an account on GitHub.

github.com

 

 

 

[참고자료]

https://github.com/swagger-api/swagger-core/wiki/Annotations-1.5.X

https://github.com/swagger-api/swagger-core/wiki/Swagger-2.X---Annotations

https://yookeun.github.io/java/2017/02/26/java-swagger/

반응형