mpOpenAPI-1.0 기능은 MicroProfile OpenAPI 스펙 버전 1.0 및 Java 인터페이스 세트의 구현과 Java 개발자가 JAX-RS 애플리케이션에서 OpenAPI v3 문서를 기본적으로 생성할 수 있게 하는 프로그래밍 모델을 제공합니다. 그런 다음 인간 친화적인 사용자 인터페이스를 사용하는 브라우저에서 mpOpenAPI-1.0 기능을 사용하여 생성된 API 문서를 볼 수 있습니다.
시작하기 전에
OpenAPI
V3 스펙 및
MicroProfile
OpenAPI 1.0 스펙에 대해 알아보십시오. 애플리케이션에서 RESTful API를 문서화하기 위해 YAML 형식 또는 JSON 형식의 정적 OpenAPI, MicroProfile OpenAPI
어노테이션 또는 OpenAPI 프로그래밍 모델을 사용할 수 있습니다.
문제점 예방: - 확장 및 확장 어노테이션은 조작 및 클래스 레벨에서만 지원됩니다. 기타 요소를 위한 확장을 지정하려면 다른 문서 메커니즘을 사용하십시오.
- 처음에 올바르지 않은 인증 신임 정보를 입력하면 OpenAPI UI가 예상치 않게 작동합니다. 나중에 올바른 신임 정보를 입력해도 문제가 지속되고 신임 정보 요청을 반복적으로 프롬프트할 수 있습니다. 페이지를 새로 고치고 올바른 신임 정보를 입력하십시오.
- mpOpenAPI-1.0을 사용으로 설정한 후 ssl-1.0 기능을 사용으로 설정하면 /openapi 또는 openapi/ui 엔드포인트에 액세스할 때 예외가 발생할 수 있습니다. 이러한 문제점을 방지하려면 두 기능을 함께 사용으로 설정하십시오. 문제점이 발생한 후 이를 해결하려면 mpOpenAPI-1.0 기능을 사용 안함으로 설정한 후 사용으로 설정하십시오.
다중 애플리케이션이 배치된 경우 OpenAPI 문서를 생성하기 위해 하나의 애플리케이션이 선택됩니다.선택된 애플리케이션을 식별하기 위해 정보 메시지가 출력됩니다. 선택된 애플리케이션이 실행 중인 경우 애플리케이션 프로세서가 기타 모든 애플리케이션을 무시합니다. 선택된 애플리케이션이 중지된 후, 다음 애플리케이션이 처리됩니다.
프로시저
- 옵션: 애플리케이션에 필요한 대로 MicroProfile 구성 메커니즘을 통해 MicroProfile OpenAPI 스펙의 다양한 파트를 구성하십시오. 애플리케이션이 시작되면 mpOpenAPI-1.0 기능이 구성된 값을 읽습니다.
- 애플리케이션에 대해 MicroProfile OpenAPI 스펙에서 사용 가능한 하나 이상의 코어 구성을 구성하십시오.
- 값을 추가하기 위해 mpOpenAPI-1.0 기능이 OpenAPI 스펙 버전 3.0에서 명시된 제한조건에 대해 애플리케이션을 위해 생성된 최종 OpenAPI 문서를 유효성 검증합니다. 유효성 검증 결과는 오류와 경고가 조합되어 있으며 콘솔 로그에 출력됩니다.
유효성 검증은 애플리케이션에서 기본적으로 사용됩니다.다음 구성을 설정하여 유효성 검증을 사용 안함으로 설정할 수 있습니다.
mp.openapi.extensions.liberty.validation=false
- 문서 메커니즘의 설명대로 결과적 OpenAPI 문서의 생성에 필요한 입력을 제공하려면 다음의 방식 중 하나 이상을 결합하여 선택하십시오.
- 부트스트랩 또는 완전한 OpenAPI 모델 트리 항목을 제공하려면 프로그래밍 모델을 사용하십시오.
- 문서 편집기를 사용하여 YAML 또는 JSON 형식으로 정적 OpenAPI 문서를 작성한 다음 openapi.yaml, openapi.yml 또는 openapi.json 파일을 애플리케이션의 META-INF 디렉토리에 배치하십시오.
- Java 코드로 MicroProfile OpenAPI 어노테이션을 지정하여 애플리케이션을 보강하고 문서화하십시오.
- 문서 메커니즘을 사용하여 빌드한 후 OpenAPI 모델을 업데이트하려면 필터를 사용하십시오.
- Liberty 서버 구성에서 mpOpenAPI-1.0 기능을 사용으로 설정하십시오.
<server>
<featureManager>
<feature>mpOpenAPI-1.0</feature>
</featureManager></server>
- 애플리케이션을 배치하십시오.
- 옵션: 유효성 검증 결과를 확인하고 애플리케이션이 OpenAPI 스펙 버전 3.0에 부합하는지 확인하십시오.
- 콘솔 로그에서 유효성 검증 오류를 확인하십시오.
- 이벤트가 오류 및 경고로 그룹화됩니다. 메시지는 또한 관련 요소를 식별할 수 있도록 생성된 문서에 해당 위치를 포함합니다.
샘플 메시지:
CWWKO1650E: Validation of the OpenAPI document produced the following error(s):
- Message: Required "scopes" field is missing or is set to an invalid value, Location: #/components/securitySchemes/reviewoauth/flows/authorizationCode
- 브라우저에서 생성된 API 문서를 보십시오. 다음 URL 중 하나를 사용하여 생성된 API 문서를 /openapi 엔드포인트에서 찾을 수 있습니다.
- 비SSL 공용 API의 경우 http://Liberty_host:http_port/openapi에서 사용자의 문서를 보십시오.
- SSL 공용 API의 경우 https://Liberty_host:https_port/openapi에서 사용자의 문서를 보십시오.
결과
OpenAPI 사용자 인터페이스는
http://Liberty_host:http_port/openapi/ui에서 UI를 표시하기 위해
/openapi로부터 정의를 렌더링합니다. SSL을 사용으로 설정하면
https://Liberty_host:https_port/openapi/ui에서 보호된 UI에 액세스할 수 있습니다.