OAS3.yml

@@ -0,0 +1,117 @@
+openapi: 3.0.0
+info:
+  title: Entities Validation Service
+  version: 0.1.0
+  description:
+    Validate Netz39 entities JSON.
+  contact:
+    email: tux@netz39.de
+
+servers:
+  - url: http://localhost:8080/v0
+tags:
+  - name: mgmt
+    description: Common management functions
+
+paths:
+  /health:
+    get:
+      summary: Provides health information about the service
+      tags:
+        - mgmt
+      operationId: health
+      responses:
+        '200':
+          description: endpoint is healthy
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/health'
+        '500':
+          $ref: '#/components/responses/InternalError'
+  /oas3:
+    get:
+      summary: get this endpoint's Open API 3 specification
+      tags:
+        - mgmt
+      responses:
+        '200':
+          description: returns the API spec
+          content:
+            text/plain:
+              schema:
+                type: string
+        '500':
+          $ref: '#/components/responses/InternalError'
+
+  /validate:
+    post:
+      summary: Validate an entity
+      tags:
+        - entities
+      requestBody:
+        content:
+          application/json:
+            schema:
+              type: object
+              description: Entity JSON
+      responses:
+        '200':
+          description: Validation result
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/validation'
+        '400':
+          $ref: '#/components/responses/InvalidInput'
+components:
+  schemas:
+    health:
+      type: object
+      properties:
+        git-version:
+          type: string
+        api-version:
+          type: string
+        timestamp:
+          type: string
+          format: date-time
+        uptime:
+          type: string
+          example: ISO8601 conforming timespan
+    validation:
+      type: object
+      properties:
+        valid:
+          type: boolean
+        findings:
+          type: array
+          items:
+            type: object
+            properties:
+              field:
+                type: string
+              message:
+                type: string
+  responses:
+    AuthenticationRequired:
+      description: Authentication is required (401)
+    NotAllowed:
+      description: The call is not allowed with the provided authentication (403)
+    InvalidInput:
+      description: One or more parameters are missing or invalid (400)
+      content:
+        text/plain:
+          schema:
+            type: string
+            example: error message
+    NotFound:
+      description: The specified object could not be found (404)
+    InternalError:
+      description: Internal error during execution (500)
+      content:
+        text/plain:
+          schema:
+            type: string
+            example: error message
+