스웨거 UI URL 기본 경로 변경 방법

Swagger UI는 OpenAPI 사양을 시각화하고 상호작용할 수 있는 훌륭한 도구입니다. Swagger UI를 사용하면서 URL이 API 문서의 구성 및 접근에 중요한 역할을 한다는 것을 알게 될 것입니다. 이 게시물에서는 Swagger UI URL의 신비를 벗기고 보다 효과적으로 사용하는 방법을 도와드리겠습니다.

💡

Apidog는 강력한 API 문서 도구입니다. 시각적 인터페이스에서 Swagger UI URL 접두사와 기타 매개변수를 쉽게 사용자 정의할 수 있습니다. 한번 해보세요!

버튼

Swagger UI란 무엇인가요?

Swagger UI는 사용자가 OpenAPI 사양 문서를 사용하여 API와 상호작용할 수 있도록 해주는 도구입니다. 사양 문서를 읽고 시각적으로 상호작용할 수 있는 형태로 표시합니다. 이는 개발자가 API를 이해하고 테스트 요청을 보내며 디버그하고 REST API를 사용하는 데 도움이 됩니다.

Swagger UI URL은 OpenAPI 사양 JSON 파일을 제공하는 엔드포인트에 해당합니다. 즉, OpenAPI JSON 파일의 위치를 가리키는 웹 주소를 제공해야 합니다. Swagger UI는 이 파일을 읽어 해당 URL을 통해 접근할 수 있는 사용자 친화적인 인터페이스를 생성합니다. 정확한 URL 구조는 서버 구성에 따라 달라질 수 있습니다.

Swagger UI 기능

Swagger UI는 API를 테스트하고 이해하며 시각화하는 다양한 기능을 제공하는 강력한 도구입니다. 아래에 몇 가지 기능이 나열되어 있습니다:

주요 기능은 다음과 같습니다:

문서 내에서 API를 실시간으로 테스트
요청 매개변수에 대한 직관적인 컨트롤
API 호출을 위한 코드 스니펫 생성
형식을 지정하기 위한 Markdown 지원
팀 협업을 위한 도구
자동 데이터 모델 시각화
API 엔드포인트 정리 및 검색

Swagger UI URL 매개변수

Swagger UI에는 동작 및 외관을 구성하기 위한 다양한 매개변수가 URL에 있습니다. 이는 Swagger UI를 사용하여 API 문서가 표시되는 방식에 영향을 미칩니다. 가장 일반적으로 사용되는 Swagger UI URL 매개변수는 다음과 같습니다:

URL:

이는 Swagger UI가 API 문서를 생성하는 데 사용할 OpenAPI 사양 파일 URL을 지정합니다. URL의 형식은 다음과 같습니다:

http://localhost:8080/swagger-ui/?url=/path/to/your/api-spec.json

ConfigUrl:

configUrl은 Swagger UI의 동작을 사용자 정의하고 변경하는 JSON 구성의 URL을 제공합니다.

http://localhost:8080/swagger-ui/?configUrl=/path/to/your/config.json

deepLinking:

API 문서 내의 개별 작업이나 태그에 대한 딥 링크를 활성화합니다. 이는 문서의 특정 부분에 대한 직접 링크를 공유할 때 유용합니다.

http://localhost:8080/swagger-ui/?url=/path/to/your/api-spec.json&deepLinking=true

oauth2RedirectUrl:

API가 OAuth 2.0 인증을 요구할 때 사용자가 성공적인 인증 후 다른 URL로 리디렉션할 수 있게 해줍니다.

http://localhost:8080/swagger-ui/?url=/path/to/your/api-spec.json&oauth2RedirectUrl=https://your-app.example.com/oauth2-redirect

defaultModelsExpandDepth:

문서의 모델의 기본 깊이를 조정합니다.

http://localhost:8080/swagger-ui/?url=/path/to/your/api-spec.json&defaultModelsExpandDepth=2

Swagger UI URL 찾는 방법

일부 사람들은 Swagger UI URL이 어디에 있는지 혼란스러워합니다. 이는 프로젝트 구성에 따라 생성됩니다. URL을 찾으려면 다음 단계를 따르세요:

프로젝트가 Swagger 문서를 생성하도록 구성되어 있는지 확인합니다.
Swagger UI에 접근하려면 API의 기본 URL과 Swagger 문서 엔드포인트를 결합해야 합니다. 이렇게 하면 Swagger UI URL이 생성됩니다.

예를 들어, API를 http://localhost:3000에서 호스팅하고 swagger 엔드포인트가 /swagger-ui/인 경우, Swagger URL은 http://localhost:8080/swagger-ui/가 됩니다.

여전히 Swagger UI URL을 찾는 데 문제가 있다면, API 생성을 위해 사용하는 프레임워크나 라이브러리의 문서를 참조할 수 있습니다. 이는 특정 설정에 대한 URL 접근 방법에 대한 정보를 제공하는 데 도움이 됩니다.

Swagger UI Defauth 경로 변경 방법

Swagger UI의 기본 경로는 서버의 구성에 따라 달라집니다. 이는 배치 위치와 Swagger UI를 배포한 위치를 기반으로 구성됩니다. 기본 URL 경로는 사용자 요구 사항과 배포에 따라 변경될 수 있습니다. URL 매개변수는 OpenAPI 사양 파일의 위치를 가리켜야 합니다.

Swagger UI URL의 기본 경로를 변경하는 방법이 여러 가지 있습니다.

Swagger 구성 파일 변경 (Apache 및 Nginx):

웹 서버를 사용하는 경우 특정 URL에서 요청을 처리하도록 서버의 구성을 변경할 수 있습니다.

Apache:

Apache의 경우, 구성을 수정하여 요청을 Swagger UI 경로로 리다이렉트할 수 있는 rewrite 규칙을 생성할 수 있습니다. 'httpd.conf' 또는 'apache2.conf'라는 이름의 구성 파일을 엽니다. 이 파일에 원하는 경로에 대한 rewrite 규칙을 추가합니다.

RewriteEngine On
RewriteRule ^/api-docs/(.*)$ /path/to/your/swagger-ui/$1 [L]

변경 사항이 반영되도록 Apache 서버를 재시작할 수 있습니다.

Nginx:

Nginx를 사용하는 경우, 요청을 처리할 위치를 정의하기 위해 서버 파일 구성을 업데이트해야 합니다. 서버 블록에서 위치를 추가합니다.

server {
    listen 80;
    server_name your-domain.com;

    location /api-docs {
        alias /path/to/your/swagger-ui;
        index index.html;
    }
}

변경 사항을 적용한 후 구문 오류가 있는지 확인하고 Nginx를 재시작합니다.

Express.js와 같은 프레임워크 사용:

Express.js를 사용하면 Swagger UI 요청을 처리하는 라우트를 구성할 수 있습니다.

Swagger UI를 제공하려면 Express.js 서버 파일에 라우트를 정의해야 합니다.

const express = require('express');
const app = express();

app.use('/custom-path', express.static('swagger-ui'));

app.listen(3000, () => {
  console.log('서버가 3000 포트에서 실행되고 있습니다.');
});

이것은 ‘custom-path’에서 Swagger UI에 접근할 수 있게 해줍니다.

Spring Boot를 활용하여 기본 경로 변경:

Spring Boot 애플리케이션에서는 ‘application.properties’ 또는 ‘application.yml’ 파일을 수정할 수 있습니다. 이러한 파일에 기본 Swagger UI 경로를 변경하기 위해 다음 속성을 추가할 수 있습니다.

springfox.documentation.swagger-ui.path=/custom-path

원하는 경로에 따라 ‘/custom-path’를 교체할 수 있습니다.

다음으로 경로를 사용자 정의하기 위해 bean을 구성해야 합니다. 이를 위해 ‘WebMvcConfigurerAdapter’를 확장할 수 있습니다.

import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.ViewControllerRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;

@Configuration
public class SwaggerUIConfiguration implements WebMvcConfigurer {

    @Override
    public void addViewControllers(ViewControllerRegistry registry) {
        registry.addRedirectViewController("/custom-path", "/swagger-ui.html");
    }
}

이 결과를 얻기 위해 Swagger에 필요한 종속성이 있는지 확인해야 합니다.

그런 다음 애플리케이션의 메인 클래스를 구성해야 합니다.

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

@Configuration
@EnableSwagger2
public class SwaggerConfiguration {

    @Bean
    public Docket api() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("your.package.name"))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("당신의 API 문서")
                .version("1.0")
                .build();
    }
}

“your.package.name”을 컨트롤러의 기본 패키지로 교체하십시오.

Swagger UI 초기화:

원하는 URL 경로를 반영하도록 ‘url’ 매개변수를 조정할 수 있습니다. 이렇게 하면 Swagger UI의 기본 경로를 변경할 수 있습니다. JavaScript에서 Swagger UI를 초기화할 때 다음과 같은 변경을 할 수 있습니다.

const ui = SwaggerUIBundle({
  url: "/custom-path/swagger.json", 
});

Swagger UI를 사용하여 API 테스트

Apidog와 같은 다른 API 테스트 도구처럼, Swagger UI는 API를 테스트하는 효율적이고 사용하기 쉬운 방법을 제공합니다. Swagger 사이트를 사용하여 API를 디버깅하고 테스트하기 위해 특정 단계를 따라야 합니다. Live Demo를 클릭하고 Swagger UI를 탐색하기 시작하세요. 이런 창이 열리는 것을 볼 수 있습니다.

POST, GET, PUT 등의 여러 HTTP/HTTPS 메소드를 탐색할 수 있습니다.

어떤 메서드를 클릭하고 탐색할 수 있습니다. POST 메서드를 클릭하면 이미지를 업로드하고 메서드의 매개변수를 업데이트하는 옵션이 표시됩니다. 'Execute'를 눌러 요청을 실행할 수 있습니다.

POST 요청에 대한 응답을 아래로 스크롤하여 확인할 수 있습니다.

마찬가지로, 제공된 다른 메서드로 작업하며 그들의 기능을 확인할 수 있습니다. 이는 Swagger UI가 어떻게 작동하는지에 대한 좋은 아이디어를 제공합니다.

Apidog를 고려하여 Swagger UI의 능력을 넘어서는 더 강력한 API 문서화를 활용하세요. Apidog는 설계, 모킹, 테스트, 버전 관리, 협업 등 API 전체 수명 주기 관리를 지원합니다.

CI/CD 통합 및 팀 워크플로와 같은 고급 기능을 통해 Apidog는 API 제공을 간소화하는 보다 완전한 도구 모음을 제공합니다. 포괄적인 플랫폼은 API 개발을 확장하고 생산성을 향상시킵니다.

Swagger UI Localhost 문제 해결

Swagger UI URL에서 localhost에 문제가 발생하면 문제를 진단하고 해결하기 위해 여러 가지 문제 해결 단계를 살펴볼 수 있습니다.

API 서버가 정상적으로 작동하고 있는지 확인합니다. 서버가 작동하지 않으면 Swagger UI가 문서를 가져올 수 없습니다.
Swagger 구성이 올바르게 설정되어 있는지 확인합니다.
정확한 엔드포인트와 함께 올바른 Swagger UI URL을 사용합니다.
브라우저의 캐시를 지웁니다. 때때로, 캐시된 데이터로 인해 예기치 않은 오류가 발생할 수 있습니다.
변경 후 API 서버와 브라우저를 모두 재시작합니다.
Swagger UI에 접근하는 데 사용하는 URL 형식을 다시 확인합니다.

결론

결론적으로, Swagger UI는 광범위한 API 관리 기술로 인해 개발자들 사이에서 빠르게 인기를 얻고 있습니다. 잘 구조화된 문서와 사용자 친화적인 인터페이스를 제공합니다. 사용자들은 라이브 API 테스트를 하면서 데이터 모델을 시각화할 수도 있어 API 테스트 및 디버깅에 좋은 선택입니다.

Swagger UI는 장점이 있지만, API를 테스트하는 동안 사용자들이 겪을 수 있는 여러 가지 제한 사항도 있습니다. 이는 개발자 간의 협업이 제한적이며 다른 API 관리 도구와의 통합을 지원하지 않습니다.