Open API3.0 with Swagger, Spring Security

OpenAPI와 Swagger의 차이

요약

공통점

• API 명세 정의에 대한 문서화

차이점

• 버전의 차이
• Swagger2.0은 swagger 측 단독으로 출시
• Open API 에서 Swagger3.0(최신버전) 합류

• 문서 형식 차이
• Swagger 2.0: Swagger라는 이름이 붙은 마지막 공식 버전으로 API 명세의 구조가 Swagger 2.0에 맞춰서 작성됨
• OpenAPI 3.x: Swagger 2.0 이후의 표준으로, 더 많은 기능을 제공하고 문서화에 있어 유연성을 제공한다. OpenAPI 3.x 명세는 Swagger 2.0에 비해 더 간결하고 명확하게 정의된다

• 구조 차이 (사용코드의 차이)
• Swagger 2.0: Swagger 2.0에서는 definitions라는 섹션에 객체 모델을 정의하고, 보안 관련 설정은 securityDefinitions에 작성
• OpenAPI 3.x: OpenAPI 3.x에서는 components라는 새로운 섹션이 도입되었으며, 이 안에 schemas, securitySchemes, responses 등의 항목들이 정의

Spring boot 에서의 Open API(Swagger3.0 설정) with Spring Security

• with 1회 호출 시점 불변성을 보장하는 생성자 바인딩을 통한 상수 관리

package com.travel.aroundthekorea.config;

import org.springframework.boot.context.properties.EnableConfigurationProperties;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.context.annotation.Profile;

import com.travel.aroundthekorea.config.constant.OpenApiProperties;

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;

@EnableConfigurationProperties(OpenApiProperties.class)
@Configuration
public class SwaggerConfig {
	private final OpenApiProperties properties;

	public SwaggerConfig(OpenApiProperties properties) {
		this.properties = properties;
	}

	@Bean
	public OpenAPI customOpenAPI(OpenApiProperties openApiProperties) {
		return new OpenAPI()
			.info(new Info()
				.title(openApiProperties.getInfo().title())
				.version(openApiProperties.getInfo().version())
				.description(openApiProperties.getInfo().description()))
			.addSecurityItem(new SecurityRequirement().addList(properties.getSecurity().scheme()))
			.components(new Components()
				.addSecuritySchemes(properties.getSecurity().scheme(),
					new SecurityScheme()
						.type(SecurityScheme.Type.HTTP)
						.scheme(properties.getSecurity().schemeName())
						.description(properties.getSecurity().description())));
	}
}

1. Spring Security 가 적용된 Swagger [Basic-Auth 기반]

1. 오른쪽 하단에 잠금이 풀린 자물쇠가 보일 것이다. 해당 버튼을 클릭하면

1. 인증을 위해 아이디와 비밀번호 설정이 나온다.
• 이 부분을 최초 1번 입력하면 밑에 있는 API 호출에서 인증이 필요한 부분을 자동으로 request에 넣어줘서 보냄으로써 편리하게 호출할 수 있다.