feat(ETU-76704): Add guidelines for new devExtensions field

.spectral-required.yml

@@ -98,6 +98,19 @@ rules:
       functionOptions:
         match: ^[a-z0-9]+(-[a-z0-9]+)*$
 
+  entur-info-metadata-devExtensions:
+    documentationUrl: "https://github.com/entur/api-guidelines/blob/main/guidelines.md#244-development-only-openapi-extensions"
+    severity: error
+    given: $.info.x-entur-metadata.devExtensions
+    then:
+      function: schema
+      functionOptions:
+        schema:
+          type: array
+          items:
+            type: string
+            pattern: ^x-.*$
+
   # -------------------------------------------------------------------------
   # 2.5 Lifecycle
   # -------------------------------------------------------------------------

.spectral.yml

@@ -244,6 +244,19 @@ rules:
       functionOptions:
         match: ^[a-z0-9]+(-[a-z0-9]+)*$
 
+  entur-info-metadata-devExtensions:
+    documentationUrl: "https://github.com/entur/api-guidelines/blob/main/guidelines.md#244-development-only-openapi-extensions"
+    severity: error
+    given: $.info.x-entur-metadata.devExtensions
+    then:
+      function: schema
+      functionOptions:
+        schema:
+          type: array
+          items:
+            type: string
+            pattern: ^x-.*$
+
   # -------------------------------------------------------------------------
   # 2.5 Lifecycle
   # -------------------------------------------------------------------------

guidelines.md

@@ -174,12 +174,13 @@ If you need to explain the required permissions in more detail, you can declare
 ### 2.4 Entur Metadata
 All OpenAPI specifications published to Enturs developer portal must declare a block `x-entur-metadata` in the `info` section of the specification.
 
-Field name|Type    |Description
-----------|--------|-----------
-id        |`string`|**REQUIRED**. Unique id for this specification. [Read more](#241-identifying-a-specification).
-audience  |`string`|**REQUIRED**. Who this specification is targeted to. Must be one of `"open"`, `"partner"`, `"internal"`, `"private"`
-owner     |`string`|**REQUIRED**. The Entur team responsible for this specification. [Read more](#242-specification-owner).
-parentId  |`string`|Id of the parent specification, used when merging. [Read more](#243-merging-specifications).
+Field name    |Type      |Description
+--------------|----------|-----------
+id            |`string`  |**REQUIRED**. Unique id for this specification. [Read more](#241-identifying-a-specification).
+audience      |`string`  |**REQUIRED**. Who this specification is targeted to. Must be one of `"open"`, `"partner"`, `"internal"`, `"private"`
+owner         |`string`  |**REQUIRED**. The Entur team responsible for this specification. [Read more](#242-specification-owner).
+parentId      |`string`  |Id of the parent specification, used when merging. [Read more](#243-merging-specifications).
+devExtensions |[`string`]|OpenAPI extensions in the specification that are used for development, but that should not be visible to consumers of the API.
 
 Example:
 ```json
@@ -229,6 +230,7 @@ There are some limitations when merging specifications:
 
 <details>
 <summary>Example</summary>
+
 For example, say you have three microservices, `alpha`, `beta` and `gamma`:
 
 Microservice `alpha` publishes the specification:
@@ -270,6 +272,35 @@ Microservice `gamma` publishes the specification:
 Here, only 1 specification will be shown on the Developer Portal, which is a combination of `alpha`, `beta` and `gamma`. Since `alpha` is the parent specification, the combined specification will use `alpha` as the base, so fields like `info.title` will be picked from there.
 </details>
 
+#### 2.4.4 Development-only OpenAPI extensions
+Sometimes there may be a need for adding OpenAPI extensions to a specification that are only meant for the development process, for example for generating server interfaces with [OpenAPIGenerator](https://openapi-generator.tech/docs/generators/kotlin-spring#supported-vendor-extensions). These extensions are only relevant for the team creating the API, not for consumers. To hide extensions like these from the OpenAPI specification that is served from the Developer Portal, use the field `x-entur-metadata.devExtensions`.
+
+<details>
+<summary>Example</summary>
+
+The extension `x-kotlin-implements` will be stripped before the specification is published to the Developer Portal.
+
+```json
+{
+  "info": {
+    "x-entur-metadata": {
+      ...,
+      "devExtensions": ["x-kotlin-implements"]
+    }
+  },
+  "components": {
+    "schemas": {
+      "Item": {
+        "type": "object",
+        "x-kotlin-implements": ["com.example.Item"],
+        ...
+      }
+    }
+  }
+}
+```
+</details>
+
 
 ### 2.5 Lifecycle
 All APIs, and endpoints within an API, follow a lifecycle with different stages that have different properties. The following sections describe a standardized way to declare an API's lifecycle status in its specification. Following this standard has several benefits:

specs/reference-spec-with-errors.json

@@ -1,7 +1,7 @@
 {
   "openapi": "3.1.0",
   "info": {
     "title": "Items API",
     "version": "1.0.0",
     "description": "A long and descriptive description",
     "termsOfService": "https://developer.entur.org/terms-of-service",
@@ -10,9 +10,10 @@
       "url": "https://entur.no",
       "email": "support@entur.no"
     },
     "x-entur-metadata": {
       "owner": "team-Api",
-      "audience": "public"
+      "audience": "public",
+      "devExtensions": ["kotlin-implements"]
     }
   },
 
@@ -61,7 +62,7 @@
         "properties": {
           "id": {
             "type": "string",
             "example": 100
           },
           "name": {
             "type": "string",
@@ -69,7 +70,7 @@
           }
         },
         "example": {
           "id": 100,
           "name": "Item 100"
         }
       },
@@ -160,8 +161,8 @@
           }
         },
         "x-entur-permissions": {
           "description": 10,
           "value": {"and": ["items:les"]}
         }
       },
       "post": {
@@ -196,11 +197,11 @@
           }
         },
         "x-entur-permissions": {
           "bar": "something",
           "description": "You need access to read organisations, and create items.",
           "value": {
             "all": [
               "organisations:le",
               {
                 "any": [
                   "items:oppret",
@@ -222,7 +223,7 @@
         "tags": [
           "Items"
         ],
         "deprecated": true,
         "summary": "Get an item",
         "description": "Get an item with given id.",
         "operationId": "getItem",

specs/reference-spec.json

@@ -13,7 +13,8 @@
     "x-entur-metadata": {
       "id": "items",
       "owner": "team-api",
-      "audience": "partner"
+      "audience": "partner",
+      "devExtensions": ["x-kotlin-implements"]
     }
   },