![[17.0.0.3 and later]](../ng_v17003plus.gif)
OpenAPI 문서 사용자 정의
externalDocs 요소 및 info 요소와 같은 요소를 사용하여 /api/explorer의 OpenAPI 사용자 인터페이스와 /api/docs 엔드포인트에서 사용 가능한 마스터 OpenAPI 문서의 측면을 사용자 정의할 수 있습니다. Liberty는 기본 경로 위치에서 사용자 정의 파일의 변경사항을 모니터링하여 마스터 OpenAPI 문서 및 UI의 변경사항을 처리하고 업데이트합니다.
시작하기 전에
OpenAPI 문서를 빌드하고 사용으로 설정하는 방법을 알아보려면 OpenAPI를 사용한 REST API 문서 생성의 내용을 참조하십시오.
샘플 OpenAPI V3 airlines 애플리케이션을 사용하여 문서를 생성하고 사용자 정의할 수 있는 UI의 예를 렌더링하십시오.
프로시저
- OpenAPI 스니펫에서 사용자 정의를 정의하십시오. OpenAPI 3.0.0 스펙의 구조를 따르는 스니펫을 작성하십시오. 스니펫은 YAML
또는 JSON 파일에 있거나 URL에서 사용할 수 있습니다.
info 요소는 제목, 설명 및 기타 정보를 제공합니다. 제목 및 설명 값을 사용자 정의할 수 있습니다. 또한 로고, 필터 상자 및 필터 단추를 편집하도록 헤더 막대를 사용자 정의할 수 있습니다. 사용자 정의 스니펫의 info 필드 내에서 x-ibm-css 필드를 사용하여 헤더 막대의 HTML 요소 스타일을 지정하는 CSS 파일의 위치를 가리키십시오.
스니펫은 자체적으로 완료할 필요가 없습니다. 다음 예제 스니펫은 OpenAPI UI의 헤더 막대 스타일을 지정하는 CSS를 가리키는 info 요소를 사용자 정의합니다.
--- openapi: 3.0.0 info: title: Airlines APIs description: Book flights and manage reservations version: 2.1.0 x-ibm-css: ${server.config.dir}/openapi/header.css
CSS는 로컬 파일이거나 URL에서 사용할 수 있습니다. 경로에는 런타임 디렉토리와 연관된 Liberty 변수가 포함될 수 있습니다.
이 CSS 파일은 유효한 것으로 간주되는 다음 형식 요구사항을 갖습니다.- CSS 파일은 .swagger-ui .headerbar로 시작하는 요소를 하나 이상 지정합니다.
- .swagger-ui .headerbar로 시작하는 CSS 요소 아래에 지정된 컨텐츠만 사용됩니다.
- CSS 파일에서 참조하는 사용자 정의 로고 파일은 PNG 형식이어야 합니다.
- 사용자 정의 로고 파일의 이름은 custom-logo.png이어야 하며 images/custom-logo.png에 위치해야 합니다.
- 로고 파일 경로는 CSS 파일과 관련이 있어야 합니다.
- CSS 파일은 background-image 특성이 url(images/custom-logo.png) 값으로 설정된 로고 이미지를 참조해야 합니다.
.swagger-ui .headerbar { background-color: #5f3345; } .swagger-ui .headerbar .headerbar-wrapper { background-image: url(images/custom-logo.png); } .swagger-ui .headerbar .filter-wrapper .filter-button { background: rgba(252, 48, 81, 0.53); color: #e8e8e8; } .swagger-ui .headerbar .filter-wrapper input[type=text] { border: 1px solid #ebebeb; }
- 사용자 정의 파일에 대한 파일 모니터링을 구성하십시오.
자동 모니터링의 기본 위치에 사용자 정의 파일을 저장하거나, 파일의 위치를 정의하도록 서버 구성을 변경할 수 있습니다. 둘 이상의 기본 사용자 정의 파일을 지정하면 모니터되는 사용자 정의 파일과 무시되는 파일을 나타내는 경고 메시지 출력이 콘솔에 표시됩니다. 모니터링하도록 선택된 사용자 정의 파일은 Liberty가 삭제될 때까지 계속 모니터됩니다.
참고: 사용자 정의 파일만 업데이트를 모니터링합니다. CSS 및 로고 파일은 모니터되지 않습니다. URL도 모니터되지 않습니다.- 기본 사용자 정의 파일 모니터링을 사용하려면 ${server.config.dir}/openapi/customization.file_type에 YAML, YML 또는 JSON 파일 유형으로 사용자 정의 스니펫을 저장하십시오.
- 옵션: Liberty 서버 구성
파일에서 스니펫을 참조하는 customization 속성이 있는
openapi 요소를 추가하십시오.
customization 속성이 명시적으로 설정되면 기본 사용자 정의 정의 위치가 모니터되지 않습니다. customization 속성은 Liberty에서 모니터링하는 YAML, YML 또는 JSON 파일을 지정할 수 있습니다. 경로에는 다음 예와 같이 런타임 디렉토리와 연관된 Liberty 변수가 포함될 수 있습니다.
<openapi customization="${server.config.dir}/custom/customInfo.yaml" />
customization 속성은 OpenAPI 스니펫을 리턴하는 URL을 지정할 수도 있습니다.
<openapi customization="http://myWebsite.com/myCustomOpenAPI" />
- 옵션: 사용자 정의 파일에 대한 파일 모니터링을 사용 안함으로 설정하십시오.
Liberty는 기본적으로 사용자 정의 파일을 지속적으로 모니터링합니다. 그러나 파일을 모니터링하면 추가 시스템 자원이 사용됩니다. 사용자 정의 파일이 없거나 사용자 정의 파일이 정적이며 변경되지 않는 경우 파일 모니터링을 끄는 것이 좋습니다.
서버 구성 파일에서 openapi 요소의 disableFileMonitor 부울 속성을 true로 설정하십시오. disableFileMonitor 속성이 true로 설정된 경우 기본 사용자 정의 정의 위치도 모니터되지 않습니다.<openapi disableFileMonitor="true" />
![[17.0.0.3 and later]](../ng_v17003plus.gif)

파일 이름: twlp_api_openapi_custom.html