Upgrade to OpenAPI 3.1 (#850)

* Upgrade to OpenAPI 3.1

Resolves issue: #839

* Update meta-information.adoc

* Update .zappr.yaml

* Update general-guidelines.adoc according to Tronje's comments.

* Update api-operation.adoc

* Repair link

Author: tfrauenstein

.zappr.yaml

@@ -1,4 +1,4 @@
-X-Zalando-Team: architecture
+X-Zalando-Team: jedi
 X-Zalando-Type: doc
 approvals:
   groups:

chapters/api-operation.adoc

@@ -3,30 +3,30 @@
 
 
 [#192]
-== {MUST} publish OpenAPI specification for non-component-internal APIs
+== {MUST} publish OpenAPI specification for APIs
 
 All service applications must publish OpenAPI specifications of their external
-APIs. While this is optional for internal APIs, i.e. APIs marked with the
-*component-internal* <<219, API audience>> group, we still recommend to do so
-to profit from the API management infrastructure.
-
-An API is published by copying its *OpenAPI specification* into the reserved
-*/zalando-apis* directory of the *deployment artifact* used to deploy the
-provisioning service. The directory must only contain *self-contained YAML*
-*files* that each describe one API (exception see <<234>>). We prefer this
-deployment artifact-based method over the past (now legacy)
-`.well-known/schema-discovery` service endpoint-based publishing process, that
-we only support for backward compatibility reasons.
-
-Background: In our dynamic and complex service infrastructure, it is important
+APIs. While this is optional for <<219, component-internal APIs>>, we still 
+recommend to do so to profit from our API management infrastructure.
+
+As described in https://cloud.docs.zalando.net/howtos/api-publishing/[How to publish API Specifications (internal_link)], 
+an API specification is published with the deployment of the implementing service 
+by copying it to the reserved `/zalando-apis` directory. The directory must only 
+contain _self-contained YAML files_ that each describe one API (exception see <<234>>). 
+*Legacy hint:* We prefer this deployment artifact-based method over the old
+`.well-known/schema-discovery` service endpoint-based publishing process
+(which still is supported for backward compatibility).
+
+*Motivation:* In our dynamic and complex service infrastructure, it is important
 to provide API client developers a central place with online access to the API
 specifications of all running applications. As a part of the infrastructure,
-the API publishing process is used to detect API specifications. The findings
-are published in the API Portal - the universal hub for all Zalando APIs.
+the API publishing process is used to detect API specifications and to make it 
+discoverable via 
+https://sunrise.zalando.net/apis?group=all[Sunrise (internal_link)] and the 
+https://apis.zalando.net/[API Portal (internal_link)].
 
-*Note:* To publish an API, it is still necessary to deploy the artifact
-successful, as we focus the discovery experience on APIs supported by running
-services.
+*Note:* APIs are discoverable only for recently running services. Hence, make sure 
+to always publish the API Specification as part of the service artifact deployment. 
 
 
 [#193]

chapters/general-guidelines.adoc

@@ -24,25 +24,28 @@ You must follow the <<api-first, API First Principle>>, more specifically:
 [#101]
 == {MUST} provide API specification using OpenAPI
 
-We use the http://swagger.io/specification/[OpenAPI specification] as standard
-to define API specification files. API designers are required to provide the API
-specification using a single *self-contained YAML* file to improve readability.
-We encourage to use *OpenAPI 3.0* version, but still support *OpenAPI 2.0*
-(a.k.a. Swagger 2).
-
-The API specification files should be subject to version control using a source
-code management system - best together with the implementing sources.
-
-You <<192, must / should publish>> the component <<219, external / internal>>
-API specification with the deployment of the implementing service, and, hence,
-make it discoverable for the group via our {api-portal}[API Portal (internal_link)].
-
-*Hint:* A good way to explore *OpenAPI 3.0/2.0* is to navigate through the
-https://openapi-map.apihandyman.io/[OpenAPI specification mind map] and use
-our https://plugins.jetbrains.com/search?search=swagger+Monte[Swagger Plugin
-for IntelliJ IDEA] to create your first API. To explore and validate/evaluate
-existing APIs the https://editor.swagger.io/[Swagger Editor] or our
-https://apis.zalando.net[API Portal] may be a good starting point.
+We use the standard provided by the https://www.openapis.org/[OpenAPI Initiative] 
+to define API specifications. API designers are required to provide the API 
+specification using a single self-contained YAML file for better readability. 
+We encourage using https://swagger.io/specification/[OpenAPI 3.1 version], 
+especially for new APIs. The API specification files should be subject to version 
+control using a source code management system, and you <<192>>.
+
+*Hint:* Our API infrastructure does not break, but might not yet fully support 
+all OpenAPI 3.1 changes (e.g. displaying `examples` in Sunrise), and continues 
+supporting OpenAPI 3.0 (and 2.0, aka Swagger 2).
+
+*Hint:* The _OpenAPI 3.1 mayor change_ is that Schema Object definitions are now 
+fully compliant with standard JSON Schema. It is an incompatible change since 
+OpenAPI-specific overrides and keywords like `example`, `nullable`, `discriminator`, `xml` 
+are removed from the Schema Object (see 
+https://www.openapis.org/blog/2021/02/16/migrating-from-openapi-3-0-to-3-1-0[OpenAPI Blog: Migrating from OpenAPI 3.0 to 3.1]). 
+Check out the https://github.com/OAI/OpenAPI-Specification/releases[OpenAPI release page] 
+for all change details. 
+
+*Hint:* You might find the https://openapi-map.apihandyman.io/[OpenAPI Map] 
+a helpful tool supporting UI navigation for the OpenAPI 3.0 specification.
+(Newer OpenAPI versions are not yet supported.) 
 
 *Hint:* We do not yet provide guidelines for https://graphql.org/[GraphQL]
 and focus on resource oriented HTTP/REST API style (and related tooling 

chapters/meta-information.adoc

@@ -50,7 +50,7 @@ Example:
 
 [source,yaml]
 ----
-openapi: 3.0.1
+openapi: 3.1.0
 info:
   title: Parcel Service API
   description: API for <...>
@@ -97,7 +97,7 @@ Example:
 
 [source,yaml]
 ----
-openapi: 3.0.1
+openapi: 3.1.0
 info:
   x-api-id: d0184f38-b98d-11e7-9c56-68f728c1ba70
   title: Parcel Service API
@@ -170,7 +170,7 @@ Example:
 
 [source,yaml]
 ----
-openapi: 3.0.1
+openapi: 3.1.0
 info:
   x-audience: company-internal
   title: Parcel Helper Service API