API 문서화와 Swagger

API 문서화

API

Application Programminf Interface 서버와 클라이언트가 데이터를 주고 받을 수 있도록 도움을 주는 매개체

API 문서화

클라이언트가 REST API 백엔드 애플리케이션에 요청을 전송하기 위해 알아야 하는 요청 정보 혹은 URL/URI 등을 문서로 정리하는 것

API 문서 생성의 자동화가 필요한 이유

1. API 문서를 수기로 작성하는 것은 비효율적
2. 기능이 추가되거나 수정되면 API 문서 역시 함께 수정되어야 하는데, 수기로 작성하면 기능을 빠뜨리거나 클라이언트에게 제공된 API 정보와 달라 에러가 발생할 수 있음

API 문서화 도구

• Swagger
• spring REST docs
• gitbook
• postman
• Doxygen
• 등등

→ 프로젝트 규모, 사용 편의성, 자동화 요구, 협업 기능 등을 기준으로 프로젝트의 특성과 팀의 요구 사항에 따라 적절한 도구 선택

Swagger

REST API를 설계, 빌드, 문서화, 소비하는 일을 도와주는 대형 도구 생태계의 지원을 받는 오픈 소스 소프트웨어 프레임워크

• API를 문서를 작성할 때 개발자가 문서를 작성하지 않아도 되므로 개발 시간을 단축할 수 있음
• Swagger UI를 이용하여 API를 쉽게 테스트할 수 있음
• API 호출 시 전달해야 할 파라미터를 확인할 수 있음
• Swagger를 이용하면 API 버전 관리가 용이해지고 다양한 API 문서를 통합할 수 있음
• Spring Boot에서 Swagger 사용 시 API문서를 생성하는 데 필요한 코드를 직접 작성하지 않아도 되므로 API 개발에 집중할 수 있음

Swagger 사용

1. 의존성 추가
→ build.gradle에 추가

implementation 'org.springdoc:springdoc-openapi-starter-webmvc-ui:2.0.2’

2. swagger config 설정
→ SwaggerConfig.java 파일 생성 후 작성

import io.swagger.v3.oas.models.OpenAPI;
import io.swagger.v3.oas.models.info.Info;
import org.springdoc.core.models.GroupedOpenApi;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration
public class SwaggerConfig {
    @Bean
    public GroupedOpenApi publicApi() {
        return GroupedOpenApi.builder()
                .group("springdoc-public")
                .pathsToMatch("문서화될 경로")
                .build();
    }
    @Bean
    public OpenAPI customOpenAPI() {
        return new OpenAPI()
                .info(new Info()
                        .title("Book Everywhere API")
                        .version("v1")
                        .description("읽는곳곳 API 명세서"));
    }
}

- GroupedOpenApi
	: API 그룹화, 어떤 경로가 문서화될지 지정

- OpenAPI
	: API 문서의 정보를 커스터마이징