setting 완료 했습니다.

Swagger 소개

swagger 는 Rest API 서비스를 설계, 제작, 테스트, 문서화 할 수 있는 frame work 입니다. 간단한 설정으로 프로젝트에서 지정한 URL들을 HTML 화면으로 확인할 수 있게 합니다. Swagger를 활용해서 API 명세를 작성한다면, 보다 쉽게 API 명세를 작성할 수 있습니다.

우리 프로젝트에서는 아래의 이유로 swagger를 채택 하여 적용 하였습니다.

API 설명서 제공

swagger는 설명서를 쉽게 생성하여 제공해주며, 서버와 연동 되어 있어서 개발 이후 서버의 유지, 보수를 할 때에도 변경된 사항이 자동으로 갱신 되므로 문서 수정, 작성의 노력이 필요 하지 않습니다.

또한 API를 통해 Parameter, 응답 정보, 예제 등 Spec 정보 전달이 용이합니다.

Test bed 역할

Rest Api 는 ui 화면이 없어서 post man , html / js 프로토 타입 테스트 등으로 테스트 할 수 밖에 없습니다.

이런 경우 ui test의 경우 사람의 시간과 노력(비용) 이 많이 들 수 밖에 없는데, swagger 는 서버와 실시간 연동 되는 테스트 기능을 제공 할 뿐 아니라, 위에서 설명 한 것과 같이 스펙 정보를 보기 좋게 제공하므로, 간단하게 실제 사용되는 parameter를 이용해 테스트 하고 응답을 확인할 수 있습니다.

협업 용이성

클라이언트 개발자와 협업시 api 명세와 테스트를 제공 하므로, api 동작에 대해 쉽게 이해 하고 협업 할 수 있습니다.

swagger 설정

gradle 의존성 설정

build.gradle 스크립트의 dependencies 에 io.springfox:springfox-boot-starter:3.0.0 모듈을 추가 해줍니다.

implementation 'io.springfox:springfox-boot-starter:3.0.0'

swagger configuration 작성

swagger를 사용하기 위해서 config file 을 생성 해야 하는데, 아래 config 파일에는 swagger를 적용하기 위한 기본적인 설정 뿐 아니라, security 설정도 포함 되어 있습니다.

src/main/java/com/team1/pinterest/Config/SwaggerConfig.java

package com.team1.pinterest.Config;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.*;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spi.service.contexts.SecurityContext;
import springfox.documentation.spring.web.plugins.Docket;

import java.util.Arrays;
import java.util.Collections;
import java.util.List;

@Configuration
public class SwaggerConfig {
    public static final String AUTHORIZATION_HEADER = "Authorization";

    private ApiInfo apiInfo() {
        return new ApiInfo("MyApp Rest APIs",
                "APIs for MyApp.",
                "1.0",
                "Terms of service",
                new Contact("test", "www.org.com", "test@emaildomain.com"),
                "License of API",
                "API license URL",
                Collections.emptyList());
    }

    @Bean
    public Docket api() {
        return new Docket(DocumentationType.OAS_30)
                .apiInfo(apiInfo())
                .securityContexts(Arrays.asList(securityContext()))
                .securitySchemes(Arrays.asList(apiKey()))
                .select()
                .apis(RequestHandlerSelectors.any())
                .paths(PathSelectors.any())
                .build();
    }

    private ApiKey apiKey() {
        return new ApiKey(AUTHORIZATION_HEADER, "JWT", "header");
    }

    private SecurityContext securityContext() {
        return SecurityContext.builder()
                .securityReferences(defaultAuth())
                .build();
    }

    List<SecurityReference> defaultAuth() {
        AuthorizationScope authorizationScope
                = new AuthorizationScope("global", "accessEverything");
        AuthorizationScope[] authorizationScopes = new AuthorizationScope[1];
        authorizationScopes[0] = authorizationScope;
        return Arrays.asList(new SecurityReference(AUTHORIZATION_HEADER, authorizationScopes));
    }

}

security config 에 AUTH_WHITELIST 설정

swagger 에 접근 할 수 있도록 whitelist 를 만들고, swagger api 문서에 필요한 모든 url을 추가 해주어야 합니다.

src/main/java/com/team1/pinterest/Security/SecurityConfig.java

"/authenticate",
"/swagger-resources/**",
"/swagger-ui/**",
"/v3/api-docs",
"/webjars/**",

swagger wagger-ui 사용법

원격 develop 브랜치로 오셔서 서버 실행 하신 다음 아래 주소로 들어가시면 됩니다. (localhost port 는 설정 하신 것으로 변경 하시면 됩니다. )

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

response 에 공백({} 또는 (no example available)) 으로 보이는 것은 저희 프로젝트에서 dto 를 responseDTO 에 한 번 더 싸서 보내게 되는데 이런 타입을 swagger 가 지원을 못하기 때문입니다.

그래서 response 형태를 보시려면 swagger 에서 api try it out 으로 직접 데이터를 넣고 response 를 받아서 확인 해야 합니다.

swagger annotation

swagger 에서 보이는 내용 들에 대한 추가할 글 또는 적용할 내용 이 있다면 코드 안에 어노테이션 을 넣어서 사용 해야 합니다. 아래의 링크 글 들이나 구글 에 swagger 3 annotation 으로 검색하여 사용 하시면 될 것 같습니다.

https://bcp0109.tistory.com/326 https://blog.jiniworld.me/91 https://velog.io/@gillog/Swagger-UI-Annotation-%EC%84%A4%EB%AA%85

swagger 보안 적용 완료

1.유저를 생성 한 후 (sign-up ) 로그인 (sign -in ) 합니다.

로그인을 하게 되면 server에 토큰이 출력 됩니다.
swagger 우측 상단의 authorize 를 클릭 합니다 .
하단의 value 칸에 토큰을 넣어야 하는데,
이때 가장 앞에 Bearer + 스페이스 바를 입력한 후 토큰 값을 넣어야 합니다 (Bearer accessToken). 참고 : https://medium.com/javarevisited/api-documentation-using-swagger-3-with-spring-boot-2-spring-security-5a0d2b0996ee https://lemontia.tistory.com/1027

Pinterest-clone-playdata / pinterest-clone

#8. swagger 사용 #22