diff --git a/microprofile/WFLY-19591_MicroProfile_OpenAPI_4.0.adoc b/microprofile/WFLY-19591_MicroProfile_OpenAPI_4.0.adoc new file mode 100644 index 00000000..cd57f61e --- /dev/null +++ b/microprofile/WFLY-19591_MicroProfile_OpenAPI_4.0.adoc @@ -0,0 +1,157 @@ +--- +// Add any category for this proposal as a yaml list, e.g. +// - core +// - management +// if missing, add it to _data/wildfly-categories and use its id +categories: +- microprofile +// Specify the stability level of the feature. +// Values can be one of: experimental preview community default +stability-level: default +// Specify the Feature Development tracker issue for the feature. +// This must be an issue tracked in https://github.com/orgs/wildfly/projects/7/views/1. +// To create a Feature Development tracker issue, go to https://github.com/wildfly/wildfly-proposals/issues/new/choose +// and select 'Feature Development' +issue: https://github.com/wildfly/wildfly-proposals/issues/647 +// Provide the github ids of the members of the feature team, organized by role. +// Provide a single id for the 'assignee' role. Use a yaml list for the 'sme' and +// 'outside-perspective' roles, even if there is only one person in a role. +feature-team: + developer: pferraro + sme: + - pferraro + outside-perspective: + - +// If this issue tracks the promotion to a higher stability level of a previously +// completed feature, provide the URL of the https://github.com/wildfly/wildfly-proposals/issues +// issue that was used to track the previous feature. +promotes: +// This should be blank during initial development of a feature. It may be used +// after the feature is completed if a subsequent issue is field to track promotion +// of this feature to a higher stability level +promoted-by: +--- +:IssueId: WFLY-19591 +:ParentIssueId: WFLY-19588 +:OldOpenAPIVersion: 3.0 +:NewOpenAPIVersion: 3.1 +:OldMicroProfileOpenAPIVersion: 3.1 +:NewMicroProfileOpenAPIVersion: 4.0 +:MicroProfileOpenAPIReleaseNotesAnchor: release_notes_40 +:SmallRyeOpenAPIVersion: 4.0.x +:MicroProfilePlatformVersion: 7.0 + += MicroProfile OpenAPI {NewMicroProfileOpenAPIVersion} +:author: Paul Ferraro +:email: paul.ferraro@redhat.com +:toc: left +:icons: font +:idprefix: +:idseparator: - + +== Overview + +WildFly currently provides MicroProfile OpenAPI {OldMicroProfileOpenAPIVersion} support to applications to expose an `/openapi` endpoint that serves an OpenAPI {OldOpenAPIVersion} document of the application's Jakarta RESTful Web Services. +This feature request upgrades support for this specification to version {NewMicroProfileOpenAPIVersion} as part of version {MicroProfilePlatformVersion} of the MicroProfile platform specification. + +Most notably, this release of the https://download.eclipse.org/microprofile/microprofile-open-api-{NewMicroProfileOpenAPIVersion}/microprofile-openapi-spec-{NewMicroProfileOpenAPIVersion}.html[MicroProfile OpenAPI specification] generates OpenAPI documentation conforming to https://github.com/OAI/OpenAPI-Specification/blob/{NewOpenAPIVersion}.0/versions/{NewOpenAPIVersion}.0.md[version {NewOpenAPIVersion} of the OpenAPI specification]. + +For details, see the https://download.eclipse.org/microprofile/microprofile-open-api-{NewMicroProfileOpenAPIVersion}/microprofile-openapi-spec-{NewMicroProfileOpenAPIVersion}.html#{MicroProfileOpenAPIReleaseNotesAnchor}[Release Notes]. + +=== User Stories + +A user would like to expose an endpoint providing an OpenAPI {NewOpenAPIVersion} document describing the Jakarta RESTful Web Services of their application. + +== Issue Metadata + +* https://issues.redhat.com/browse/{IssueId}[{IssueId}] + +=== Related Issues + +* https://issues.redhat.com/browse/{ParentIssueId}[{ParentIssueId}] + +=== Affected Projects or Components + +* WildFly Quickstarts (updates to version numbers references only) + +=== Other Interested Projects + +* https://github.com/eclipse/microprofile-open-api[Eclipse MicroProfile OpenAPI] +* https://github.com/smallrye/smallrye-open-api[SmallRye OpenAPI] + +=== Relevant Installation Types + +* Traditional standalone server (unzipped or provisioned by Galleon) +* Managed domain +* OpenShift Source-to-Image (S2I) +* Bootable jar + +== Requirements + +* Upgrade version of MicroProfile OpenAPI specification API from {OldMicroProfileOpenAPIVersion} to {NewMicroProfileOpenAPIVersion}. +* Upgrade version of SmallRye OpenAPI to the final {SmallRyeOpenAPIVersion} release that implements the new spec version. + +=== Changed requirements + +N/A + +=== Non-Requirements + +N/A + +=== Future Work + +N/A + +== Backwards Compatibility + +=== Default Configuration + +N/A + +=== Importing Existing Configuration + +N/A + +=== Deployments + +See https://download.eclipse.org/microprofile/microprofile-open-api-{NewMicroProfileOpenAPIVersion}/microprofile-openapi-spec-{NewMicroProfileOpenAPIVersion}.html#{MicroProfileOpenAPIReleaseNotesAnchor}[Release Notes] for the list of incompatible changes between the current and previous versions of the MicroProfile OpenAPI specification. + +=== Interoperability + +N/A + +== Implementation Plan + +The implementation of MicroProfile OpenAPI {NewMicroProfileOpenAPIVersion} is provided by SmallRye OpenAPI {SmallRyeOpenAPIVersion}. +The implemetation plan consist of simple version upgrade of the following components: + +* org.eclipse.microprofile.openapi API +* org.eclipse.microprofile.openapi TCK +* io.smallrye.openapi + +== Admin Clients + +N/A + +== Security Considerations + +N/A + +[[test_plan]] +== Test Plan + +The following testsuites will be used to validate this feature: + +* Version {NewMicroProfileOpenAPIVersion} of the MicroProfile OpenAPI TCK +* The existing MicroProfile OpenAPI tests within WildFly's MicroProfile integration testsuite. +* The MicroProfile OpenAPI tests from https://github.com/jboss-eap-qe/eap-microprofile-test-suite + +== Community Documentation + +References the MicroProfile OpenAPI and OpenAPI specifications need to be updated to reflect the current versions. + +== Release Note Content + +Support for the MicroProfile OpenAPI specification was updated from {OldMicroProfileOpenAPIVersion} to {NewMicroProfileOpenAPIVersion}. +