[17.0.0.1 and later]

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단계를 완료하십시오.

프로시저

  1. swaggerDefinition 스니펫을 작성하여 겹쳐쓸 필드가 포함된 JSON 또는 YAML Swagger 스니펫을 지정하십시오. info, schemes, consumes, producesexternalDocs 필드를 겹쳐쓸 수 있습니다.

    예를 들어 다음 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"
         }
      }
    }

    titledescription 값에 추가하여, /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;
    }
  2. 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 문서에서 대체됩니다. 두 번째 웹 애플리케이션이 서버에 배치되면, 단일 애플리케이션 최적화의 영향을 받은 모든 필드가 기본값으로 되돌려집니다.


주제의 유형을 표시하는 아이콘 태스크 주제

파일 이름: twlp_api_discovery_swagger_def.html