[Swagger] 파비콘, 타이틀 커스터마이징

API 문서는 Swagger 를 애용중이다.

 

하지만 개발하는 서비스가 많아지다보니 Swagger UI 창을 여러 개 열어두고 작업하는데

탭이 점점 늘어날수록 어떤 탭이 어떤 서비스의 문서인지 헷갈리기 시작했다.

 

 

이미지에서는 Swagger UI 탭을 두개만 띄워놓고 있지만, 많을땐 세네개씩 띄워 작업하다보니

어떤 서비스인지 매번 클릭해서 확인해야 하는 상황이었다.

 

 

 

 

헷갈리지 않게 파비콘과 탭 타이틀을 변경해보자!

초반에는 파비콘을 변경하는 것보다 직접 눌러보며 구분하는 편이 덜 번거로웠지만

이제는 슬슬 효율성의 정도가 역전되어 가고있어서 파비콘을 변경하기로 결정했다.

 

 

 

 

우선 Swagger Module 을 뜯어보자

보통 swagger는 main.ts 같은 entry point 에서 설정한다.

현재는 .setup() 함수에 swagger ui 접속 경로, 생성 모듈, API 문서 설정, Swagger UI 정렬 옵션 만 보내주고있다.

 

 

 

여기서 .setup() 함수를 뜯어보면

static setup(path: string, app: INestApplication, documentOrFactory: OpenAPIObject | (() => OpenAPIObject), options?: SwaggerCustomOptions): void;

이렇게 구성되어있는데

우리가 확인할곳은 가장 마지막인 options 인자이다.

 

 

 

options 의 많은 기능 중

export interface SwaggerCustomOptions {
    useGlobalPrefix?: boolean; // true 일 겨우 Swagger UI 경로 앞에 /api 가 자동으로 붙음
    explorer?: boolean; // API Exporer 기능 활성 여부 (왼쪽 상단 Explorer 탭)
    swaggerOptions?: SwaggerUiOptions; // Swagger UI의 공식 설정 옵션들을 넣을 수 있음
    customCss?: string; // Swagger UI에 사용자 정의 CSS 문자열을 작성해서 넣을 수 있음
    customCssUrl?: string | string[]; // 외부 CSS URL 주입
    customJs?: string | string[]; // 외부 JavaScript 파일 URL 주입 (스크립트 로딩용)
    customJsStr?: string | string[]; // JavaScript 코드를 직접 문자열로 넣을 수 있음
    customfavIcon?: string; // 파비콘으로 사용할 이미지 URL 또는 경로
    customSwaggerUiPath?: string; // Swagger UI 가 mount될 경로
    swaggerUrl?: string; // Swagger 문서의 JSON URL 지정
    customSiteTitle?: string; // Swagger 페이지의 HTML title 값 (브라우저 탭 제목)
    validatorUrl?: string; // Swagger JSON 스펙 검증용 Validator의 URL
    url?: string; // Swagger 문서의 JSON URL
    urls?: Record<'url' | 'name', string>[]; // 여러개의 Swagger 문서 URL 을 제공할 때 (드롭다운으로 선택)
    jsonDocumentUrl?: string; // Swagger 문서 Json 파일을 외부에서 URL 로 주입
    yamlDocumentUrl?: string; // Swagger 문서를 YAML 형식으로 제공 할 수 있음
    patchDocumentOnRequest?: <TRequest = any, TResponse = any>(req: TRequest, res: TResponse, document: OpenAPIObject) => OpenAPIObject; // Swagger 문서 요청 시 동적으로 반환할 수 있는 함수
}

 

 

 

파비콘을 변경하는 customfavIcon과, 타이틀을 변경하는 customSiteTitle 을 사용하도록 하겠다.

 

 

 

 

 

.setup() 함수에 customfavIcon과 customSiteTitle를 넘겨주면 간단하게 적용된다.

 

 

 

 

 

 

 

 

 

이제 확실히 구분이 잘 된다!

파비콘과 타이틀을 변경해주는 것 만으로도 다중 서비스 개발 환경에서 작업 효율성에 크게 도움을 줄 수 있었다.