refactor(model-server): deduplicate problem types in OpenAPI specs

languitar · languitar · commit 5b1f06548461 · 2024-07-30T10:25:18.000+02:00
Use a file $ref instead of duplicating the type to prevent potentially
diverging definitions.

This does not yet prevent the duplication of generated code.
diff --git a/model-server-openapi/specifications/model-server-operative.yaml b/model-server-openapi/specifications/model-server-operative.yaml
@@ -77,56 +77,9 @@ components:
       content:
         application/problem+json:
           schema:
-            $ref: '#/components/schemas/Problem'
+            $ref: 'problem.yaml#/Problem'
 
   schemas:
-    # From https://opensource.zalando.com/restful-api-guidelines/models/problem-1.0.1.yaml
-    Problem:
-      type: object
-      properties:
-        type:
-          type: string
-          format: uri-reference
-          description: >
-            A URI reference that uniquely identifies the problem type only in the
-            context of the provided API. Opposed to the specification in RFC-9457,
-            it is neither recommended to be dereferenceable and point to a
-            human-readable documentation nor globally unique for the problem type.
-          default: 'about:blank'
-          example: '/some/uri-reference'
-        title:
-          type: string
-          description: >
-            A short summary of the problem type. Written in English and readable
-            for engineers, usually not suited for non technical stakeholders and
-            not localized.
-          example: some title for the error situation
-        status:
-          type: integer
-          format: int32
-          description: >
-            The HTTP status code generated by the origin server for this occurrence
-            of the problem.
-          minimum: 100
-          maximum: 600
-          exclusiveMaximum: true
-        detail:
-          type: string
-          description: >
-            A human readable explanation specific to this occurrence of the
-            problem that is helpful to locate the problem and give advice on how
-            to proceed. Written in English and readable for engineers, usually not
-            suited for non technical stakeholders and not localized.
-          example: some description for the error situation
-        instance:
-          type: string
-          format: uri-reference
-          description: >
-            A URI reference that identifies the specific occurrence of the problem,
-            e.g. by adding a fragment identifier or sub-path to the problem type.
-            May be used to locate the root of this problem in the source code.
-          example: '/some/uri-reference#specific-occurrence-context'
-
     AboutV1:
       x-modelix-media-type: 'application/x.modelix.about+json;version=1'
       description: Information about the model server
diff --git a/model-server-openapi/specifications/model-server-v1.yaml b/model-server-openapi/specifications/model-server-v1.yaml
@@ -185,76 +185,28 @@ components:
       content:
         application/problem+json:
           schema:
-            $ref: '#/components/schemas/Problem'
+            $ref: 'problem.yaml#/Problem'
     "401":
       description: "Unauthorized"
       content:
         application/problem+json:
           schema:
-            $ref: '#/components/schemas/Problem'
+            $ref: 'problem.yaml#/Problem'
     "403":
       description: "Forbidden"
       content:
         application/problem+json:
           schema:
-            $ref: '#/components/schemas/Problem'
+            $ref: 'problem.yaml#/Problem'
     "404":
       description: "Not Found"
       content:
         application/problem+json:
           schema:
-            $ref: '#/components/schemas/Problem'
+            $ref: 'problem.yaml#/Problem'
     GeneralError:
       description: Unexpected error
       content:
         application/problem+json:
           schema:
-            $ref: '#/components/schemas/Problem'
-
-  schemas:
-    # From https://opensource.zalando.com/restful-api-guidelines/models/problem-1.0.1.yaml
-    Problem:
-      type: object
-      properties:
-        type:
-          type: string
-          format: uri-reference
-          description: >
-            A URI reference that uniquely identifies the problem type only in the
-            context of the provided API. Opposed to the specification in RFC-9457,
-            it is neither recommended to be dereferenceable and point to a
-            human-readable documentation nor globally unique for the problem type.
-          default: 'about:blank'
-          example: '/some/uri-reference'
-        title:
-          type: string
-          description: >
-            A short summary of the problem type. Written in English and readable
-            for engineers, usually not suited for non technical stakeholders and
-            not localized.
-          example: some title for the error situation
-        status:
-          type: integer
-          format: int32
-          description: >
-            The HTTP status code generated by the origin server for this occurrence
-            of the problem.
-          minimum: 100
-          maximum: 600
-          exclusiveMaximum: true
-        detail:
-          type: string
-          description: >
-            A human readable explanation specific to this occurrence of the
-            problem that is helpful to locate the problem and give advice on how
-            to proceed. Written in English and readable for engineers, usually not
-            suited for non technical stakeholders and not localized.
-          example: some description for the error situation
-        instance:
-          type: string
-          format: uri-reference
-          description: >
-            A URI reference that identifies the specific occurrence of the problem,
-            e.g. by adding a fragment identifier or sub-path to the problem type.
-            May be used to locate the root of this problem in the source code.
-          example: '/some/uri-reference#specific-occurrence-context'
+            $ref: 'problem.yaml#/Problem'
diff --git a/model-server-openapi/specifications/model-server-v2.yaml b/model-server-openapi/specifications/model-server-v2.yaml
@@ -447,31 +447,31 @@ components:
       content:
         application/problem+json:
           schema:
-            $ref: '#/components/schemas/Problem'
+            $ref: 'problem.yaml#/Problem'
     "401":
       description: "Unauthorized"
       content:
         application/problem+json:
           schema:
-            $ref: '#/components/schemas/Problem'
+            $ref: 'problem.yaml#/Problem'
     "403":
       description: "Forbidden"
       content:
         application/problem+json:
           schema:
-            $ref: '#/components/schemas/Problem'
+            $ref: 'problem.yaml#/Problem'
     "404":
       description: "Not Found"
       content:
         application/problem+json:
           schema:
-            $ref: '#/components/schemas/Problem'
+            $ref: 'problem.yaml#/Problem'
     GeneralError:
       description: Unexpected error
       content:
         application/problem+json:
           schema:
-            $ref: '#/components/schemas/Problem'
+            $ref: 'problem.yaml#/Problem'
 
     "versionDelta":
       description: OK
@@ -490,53 +490,6 @@ components:
             type: string
 
   schemas:
-    # From https://opensource.zalando.com/restful-api-guidelines/models/problem-1.0.1.yaml
-    Problem:
-      type: object
-      properties:
-        type:
-          type: string
-          format: uri-reference
-          description: >
-            A URI reference that uniquely identifies the problem type only in the
-            context of the provided API. Opposed to the specification in RFC-9457,
-            it is neither recommended to be dereferenceable and point to a
-            human-readable documentation nor globally unique for the problem type.
-          default: 'about:blank'
-          example: '/some/uri-reference'
-        title:
-          type: string
-          description: >
-            A short summary of the problem type. Written in English and readable
-            for engineers, usually not suited for non technical stakeholders and
-            not localized.
-          example: some title for the error situation
-        status:
-          type: integer
-          format: int32
-          description: >
-            The HTTP status code generated by the origin server for this occurrence
-            of the problem.
-          minimum: 100
-          maximum: 600
-          exclusiveMaximum: true
-        detail:
-          type: string
-          description: >
-            A human readable explanation specific to this occurrence of the
-            problem that is helpful to locate the problem and give advice on how
-            to proceed. Written in English and readable for engineers, usually not
-            suited for non technical stakeholders and not localized.
-          example: some description for the error situation
-        instance:
-          type: string
-          format: uri-reference
-          description: >
-            A URI reference that identifies the specific occurrence of the problem,
-            e.g. by adding a fragment identifier or sub-path to the problem type.
-            May be used to locate the root of this problem in the source code.
-          example: '/some/uri-reference#specific-occurrence-context'
-
     VersionDelta:
       title: VersionDelta
       type: object
diff --git a/model-server-openapi/specifications/problem.yaml b/model-server-openapi/specifications/problem.yaml
@@ -0,0 +1,46 @@
+# From https://opensource.zalando.com/restful-api-guidelines/models/problem-1.0.1.yaml
+Problem:
+  type: object
+  properties:
+    type:
+      type: string
+      format: uri-reference
+      description: >
+        A URI reference that uniquely identifies the problem type only in the
+        context of the provided API. Opposed to the specification in RFC-9457,
+        it is neither recommended to be dereferenceable and point to a
+        human-readable documentation nor globally unique for the problem type.
+      default: 'about:blank'
+      example: '/some/uri-reference'
+    title:
+      type: string
+      description: >
+        A short summary of the problem type. Written in English and readable
+        for engineers, usually not suited for non technical stakeholders and
+        not localized.
+      example: some title for the error situation
+    status:
+      type: integer
+      format: int32
+      description: >
+        The HTTP status code generated by the origin server for this occurrence
+        of the problem.
+      minimum: 100
+      maximum: 600
+      exclusiveMaximum: true
+    detail:
+      type: string
+      description: >
+        A human readable explanation specific to this occurrence of the
+        problem that is helpful to locate the problem and give advice on how
+        to proceed. Written in English and readable for engineers, usually not
+        suited for non technical stakeholders and not localized.
+      example: some description for the error situation
+    instance:
+      type: string
+      format: uri-reference
+      description: >
+        A URI reference that identifies the specific occurrence of the problem,
+        e.g. by adding a fragment identifier or sub-path to the problem type.
+        May be used to locate the root of this problem in the source code.
+      example: '/some/uri-reference#specific-occurrence-context'
diff --git a/model-server/build.gradle.kts b/model-server/build.gradle.kts
@@ -201,7 +201,7 @@ spotless {
 
 // OpenAPI integration
 val basePackage = project.group.toString()
-val openAPIgenerationPath = "${project.layout.buildDirectory.get()}/generated/openapi"
+val openApiGenerationPath = project.layout.buildDirectory.get().dir("generated").dir("openapi")
 
 // Pairs of the different OpenAPI files we use. Each pair must have its own 'category' as first argument as these
 // are used to generate corresponding packages
@@ -215,7 +215,7 @@ val openApiFiles = listOf(
 openApiFiles.forEach {
     val targetTaskName = "openApiGenerate-${it.second}"
     val targetPackageName = "$basePackage.api.${it.first}"
-    val outputPath = "$openAPIgenerationPath/${it.first}"
+    val outputPath = "$openApiGenerationPath/${it.first}"
     tasks.register<GenerateTask>(targetTaskName) {
         // we let the Gradle OpenAPI generator plugin build data classes and API interfaces based on the provided
         // OpenAPI specification. That way, the code is forced to stay in sync with the API specification.
diff --git a/model-server/src/main/kotlin/org/modelix/model/server/Main.kt b/model-server/src/main/kotlin/org/modelix/model/server/Main.kt
@@ -240,6 +240,11 @@ object Main {
                         get("swagger") {
                             call.respondRedirect("swagger/v2", false)
                         }
+                        // The swagger UI plugin automatically serves the configured OpenAPI specification. However,
+                        // it does not include potentially linked files. Therefore, we need to serve those on
+                        // appropriate paths on our own to not break the Swagger UI.
+                        staticResources("swagger/v2", "api")
+                        staticResources("swagger/v1", "api")
                     }
                 }
             }

Original file line number	Diff line number	Diff line change
`@@ -240,6 +240,11 @@ object Main {`
`240`	`240`	`get("swagger") {`
`241`	`241`	`call.respondRedirect("swagger/v2", false)`
`242`	`242`	`}`
	`243`	`+ // The swagger UI plugin automatically serves the configured OpenAPI specification. However,`
	`244`	`+ // it does not include potentially linked files. Therefore, we need to serve those on`
	`245`	`+ // appropriate paths on our own to not break the Swagger UI.`
	`246`	`+ staticResources("swagger/v2", "api")`
	`247`	`+ staticResources("swagger/v1", "api")`
`243`	`248`	`}`
`244`	`249`	`}`
`245`	`250`	`}`