[TIL] 내일배움캠프 27일차 - 스웨거

오늘의 학습 키워드📚

스웨거

• 스웨거란 Web API 문서화를 위한 도구이다. 직접 API 문서를 작성하는 일은 굉장히 번거롭고 힘든 작업인데 스웨거를 사용하면 코드 단에서 작성한 api를 자동으로 문서화해주는 아주 좋은 프레임워크이다.

// Swagger
implementation group: 'org.springdoc', name: 'springdoc-openapi-starter-webmvc-ui', version: '2.2.0'

build.gradle의 dependency에 해당 코드를 추가한다.
그리고 localhost:포트번호/swagger-ui/index.html으로 접속하면 해당 프로젝트의 api 문서가 자동으로 정리된다.

package com.sparta.myselectshop.config;

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() {
        // pathsToMatch로 원하는 경로의 api만 나오도록 설정
        return GroupedOpenApi.builder()
                .group("api")
                .pathsToMatch("/api/**")
                .build();
    }

    @Bean
    public OpenAPI springShopOpenAPI() {
        String title = "My Select Shop";
        String description = "Spring 숙련 주차 강의 프로젝트";

        Info info = new Info().title(title).description(description).version("1.0.0");

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

스웨거를 설정해주는 클래스이다. 이외에 정말 많은 기능들이 있는데 그냥 간단하게 표시만 하도록 했다.

        http.authorizeHttpRequests((authorizeHttpRequests) ->
                authorizeHttpRequests
                        .requestMatchers(PathRequest.toStaticResources().atCommonLocations()).permitAll() // resources 접근 허용 설정
                        .requestMatchers("/").permitAll() // 메인 페이지 요청 허가
                        .requestMatchers("/api/user/**").permitAll() // '/api/user/'로 시작하는 요청 모두 접근 허가
                        .requestMatchers("/swagger*/**").permitAll()
                        .requestMatchers("/v3/api-docs/**").permitAll()
                        .requestMatchers("/v3/api-docs").permitAll()
                        .requestMatchers("/swagger-ui.html", "/swagger-ui/**", "/api-docs", "/api-docs/**").hasRole("USER")
                        .anyRequest().authenticated() // 그 외 모든 요청 인증처리
        );

스프링 시큐리티를 사용할 경우 스웨거의 주소를 접근 허가해줘야 스웨거 문서가 정상적으로 출력된다.
하나라도 빼먹으면 스웨거 문서가 표시되지 않거나 default 스웨거 문서가 열리므로 잘 추가해주어야 한다.

진짜 깔끔하게 api 문서가 작성됐다. 여기서 코드를 수정하면 거기에 맞게 스웨거가 자동으로 수정된다.
Controller에서도 표시 제목이나 이것저것 설정할 수 있고 설정하는 애너테이션이 정말 많다고 한다. 앞으로 진행하면서 많이 사용해봐야겠다.

api 문서를 작성하는 방법도 몰랐고 어떤 항목들을 넣어야 하는지 헷갈렸는데 이번 프로젝트 뿐만 아니라 앞으로 계속 많이 사용하게 될 것 같다.

---

오늘의 회고💬

강의를 듣고 어려운 부분에 대한 복습을 진행했다. 아직 모르는 것이 많지만 그래도 천천히 하다보니 이전보다는 훨씬 나은 것 같다.

 

내일의 계획📜

내일은 진짜로 todo 개인 과제를 진행해야 한다!!!