Swagger를 사용해서 쉽게 api명세서를 만들어보자!

 

나는 프론트앤드 개발자들과 협업을 통해 프로젝트를 진행중이다.

간단한 프로젝트니 api가 별로 없다고 생각할 수 있겠지만 추후 지속적인 개발을 통해 api가 수도없이 많아졌을 때,

하나하나 보면서 api명세서를 눈빠지게 작성하고 있을수는 없다.

 

개발환경 : Springboot 3.x, Java17

 

Swagger란 무엇인가?

Swagger는 RESTful API를 설계, 빌드, 문서화, 소비하기 위한 도구 모음이다. 이를 통해 API를 자동으로 문서화하고, 클라이언트와 서버 간의 원활한 소통을 가능하게 한다. Swagger는 특히 대규모 프로젝트에서 API 설계와 문서화를 일관되게 관리하는 데 유용하다.

 

1. build.gradle에 의존성 추가하기

implementation 'org.springdoc:springdoc-openapi-starter-webmvc-ui:2.2.0'

 

의존성을 추가해주자.

 

2. SwaggerConfig.java 파일 생성하기

나는 Config파일은 common폴더를 따로 만들어서 보관해주었다.

 

package com.swyp.playground.common.config;

import io.swagger.v3.oas.models.Components;
import io.swagger.v3.oas.models.OpenAPI;
import io.swagger.v3.oas.models.info.Info;
import io.swagger.v3.oas.models.security.SecurityRequirement;
import io.swagger.v3.oas.models.security.SecurityScheme;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration
public class SwaggerConfig {

    @Bean
    public OpenAPI openAPI() {
        SecurityScheme securityScheme = new SecurityScheme()
                .type(SecurityScheme.Type.HTTP)
                .scheme("bearer")
                .bearerFormat("JWT")
                .name("Authorization")
                .in(SecurityScheme.In.HEADER);

        Components components = new Components()
                .addSecuritySchemes("bearerAuth", securityScheme);

        SecurityRequirement securityRequirement = new SecurityRequirement().addList("bearerAuth");

        Info info = new Info()
                .title("Playground Swagger")
                .description("Playground API Doc");


        return new OpenAPI()
                .components(components)
                .addSecurityItem(securityRequirement)
                .info(info);
    }
}

 

3. 스웨거 url로 접속해보기

 

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

해당 url을 통해서 스웨거에 접속할 수 있다.

(springboot 3.x에서는 해당url로 들어가는데 더 낮은 버젼에서는 다른 Url로 알고있다. 그건 찾아보자 ㅈㅅ)

 

 

 

접속에 문제있음?

 

1. SecurityConfig부분에 Swagger관련 url을 열어뒀는지 확인해보자.

@Bean
public SecurityFilterChain securityFilterChain(HttpSecurity http) throws Exception {
    http
            .csrf(csrf -> csrf.disable())
            .authorizeHttpRequests(auth -> auth
                    .requestMatchers("/swagger-ui/**",
                            "/v3/api-docs/**",
                            "/swagger-resources/**",
                            "/auth/signup",
                            "/auth/login"
                            ).permitAll()
                    .anyRequest().authenticated()
            )
            .addFilterBefore(new JwtAuthFilter(tokenProvider, redisService),
                    org.springframework.security.web.authentication.UsernamePasswordAuthenticationFilter.class);
    return http.build();
}

나는 회원가입, 로그인, swagger만 permitall을 통해 인증없이 들어갈 수 있도록 해놨다.

 

 

이건 뭐임?

        SecurityScheme securityScheme = new SecurityScheme()
                .type(SecurityScheme.Type.HTTP)
                .scheme("bearer")
                .bearerFormat("JWT")
                .name("Authorization")
                .in(SecurityScheme.In.HEADER);

        Components components = new Components()
                .addSecuritySchemes("bearerAuth", securityScheme);

        SecurityRequirement securityRequirement = new SecurityRequirement().addList("bearerAuth");

 

JWT를 통해 로그인이 구현이 된 상태라면 해당 코드를 통해서 권한이 필요한 api임을 명시해주는게 프론트, 백 서로에게 좋다. 

(사실상 편의때문에 달아놓은 것)

아래의 이미지를 보면 required라고 빨간글씨로 적힌게 보일텐데, 이건 권한이 필요하다는 의미이다.

 

꼭 해당 url에

@SecurityRequirement(name = "bearerAuth")

이 어노테이션을 달아주자. (이거 안달면 소용없음)

@SecurityRequirement(name = "bearerAuth")
@PostMapping("/users/delete/{id}")
public ResponseEntity<Void> deleteParent(@PathVariable Long id) {
    parentService.deleteParentById(id);
    return ResponseEntity.noContent().build();
}