![[17.0.0.1 and later]](../ng_v17001plus.gif)
Swagger 2.0 문서 필드 겹쳐쓰기
server.xml 파일의 swaggerDefinition 속성을 사용하여 /docs 및 /explorer 엔드포인트에서 제공하는 Swagger 2.0 문서의 일부 필드를 겹쳐쓸 수 있습니다.
시작하기 전에
우선 apiDiscovery-1.0 기능을 server.xml 파일에 추가한 후에 Liberty REST 엔드포인트에서 Swagger 2.0 문서를 노출해야 합니다. Liberty 서버에서 REST API 문서 발견에 있는 프로시저의 1단계와 2단계를 완료하십시오.
프로시저
- swaggerDefinition 스니펫을 작성하여 겹쳐쓸 필드가 포함된 JSON 또는 YAML Swagger 스니펫을 지정하십시오.
info, schemes, consumes, produces 및
externalDocs 필드를 겹쳐쓸 수 있습니다.
예를 들어 다음 swaggerDefinition 스니펫은 /explorer HTML 페이지에 있는 description, title 및 기타 info 필드를 변경합니다.
{ "swagger" : "2.0", "info":{ "description":"My description", "version":"1.0.0", "title":"My title", "x-ibm-css":"${server.config.dir}/css/acme-banner.css", "termsOfService":"http://swagger.io/terms/", "contact":{ "email":"apiteam@swagger.io" }, "license":{ "name":"Apache 2.0", "url":"http://www.apache.org/licenses/LICENSE-2.0.html" } } }
title 및 description 값에 추가하여, /explorer HTML 페이지의 배너 및 로고 HTML 요소를 사용자 정의할 수 있습니다. swaggerDefinition 스니펫의 info 필드 내에서 배너 및 로고 부분을 대체하는 CSS 파일의 위치를 지시하는 x-ibm-css 필드를 지정할 수 있습니다. 이 CSS 파일에는 다음 형식 요구사항이 있습니다.
- CSS 파일은 .swagger-section #header CSS 요소를 지정해야 합니다.
- 새 로고는 images/custom-logo.png 형식을 사용해야 합니다. 여기서 custom-logo는 이미지 파일의 이름입니다. CSS 파일에 상대적인 로고 파일 경로를 지정하십시오.
- CSS 파일은 url(images/custom-logo.png) 값으로 설정된 background-image 특성의 사용자 정의 로고 이미지를 참조해야 합니다.
- 로고 파일은 PNG 형식이어야 합니다.
대체 CSS 파일의 예제는 다음과 같습니다.
.swagger-section #header { background-image: url(images/custom-logo.png); background-repeat: no-repeat; background-color: lightslategray; background-position-x: 28px; padding-top: 20px; padding-right: 0px; padding-bottom: 20px; padding-left: 5px; height: 75px; }
- swaggerDefinition 속성을 server.xml 파일에 추가하십시오.
swaggerDefinition 속성 값은 다음 값 중 하나일 수 있습니다.
- .json 또는 .yaml 파일 확장자로 끝나는 로컬 파일의 경로. 이 경로에는 런타임 디렉토리와 연관된 Liberty 변수가
포함될 수 있습니다. 예를 들면 다음과 같습니다.
<apiDiscovery swaggerDefinition="${server.config.dir}/custom/swaggerDef.yaml" />
- http 또는 https로 시작되는 Swagger 스니펫의
절대 URL. 예를 들면
다음과 같습니다.
<apiDiscovery swaggerDefinition="http://mycompany.com/api/swaggerDef.json" />
- 서버에 배치된 애플리케이션의 컨텍스트 루트. 이 컨텍스트 루트는
슬래시(/)로 시작됩니다. 예를 들면
다음과 같습니다.
<apiDiscovery swaggerDefinition="/myApplication" />
하나의 배치된 웹 애플리케이션이 포함된 Liberty 서버의 사용자 경험을 개선하기 위해 웹 애플리케이션의 Swagger 문서는 swaggerDefinition 스니펫으로 사용됩니다. swaggerDefinition 속성이 server.xml에서 정의되지 않은 경우에도 애플리케이션의 모든 필드는 /docs 엔드포인트가 제공하는 Swagger 문서에서 대체됩니다. 두 번째 웹 애플리케이션이 서버에 배치되면, 단일 애플리케이션 최적화의 영향을 받은 모든 필드가 기본값으로 되돌려집니다.
- .json 또는 .yaml 파일 확장자로 끝나는 로컬 파일의 경로. 이 경로에는 런타임 디렉토리와 연관된 Liberty 변수가
포함될 수 있습니다. 예를 들면 다음과 같습니다.

파일 이름: twlp_api_discovery_swagger_def.html