convert openapi description to yaml

and split into separate files for facilitating maintenance

api/v1/openapi.yaml

@@ -0,0 +1,72 @@
+openapi: 3.0.1
+info:
+  title: WeGA API
+  description: 'The OpenAPI documentation for the RESTful interface of the Carl-Maria-von-Weber-Gesamtausgabe. <br/> (No registration, authentication, or API key is required) <br/> For feedback or requests about this API please contact stadler@weber-gesamtausgabe.de or start the discussion at https://github.com/Edirom/WeGA-WebApp'
+  version: 1.1.0
+servers:
+  - url: 'http://localhost:8080/exist/apps/WeGA-WebApp/api/v1'
+tags:
+  - name: Documents
+    description: Access to the documents of the WeGA digital edition
+  - name: Search
+    description: Access to search functions of the WeGA digital edition
+  - name: Code Samples
+    description: Access to encoding features
+  - name: Application
+    description: Access to application settings
+  - name: Facets
+    description: Access to facets for filtering result sets
+  - name: Repositories
+    description: Access to items within the WeGA digital edition by repository
+paths:
+  /documents:
+    $ref: "./openapi/paths/documents.yaml"
+  /repositories:
+    $ref: "./openapi/paths/repositories.yaml"
+  /repositories/items:
+    $ref: "./openapi/paths/repositories-items.yaml"
+  /search/entity:
+    $ref: "./openapi/paths/search-entity.yaml"
+  /documents/{docID}:
+    $ref: "./openapi/paths/documents-docID.yaml"
+  /documents/findByDate:
+    $ref: "./openapi/paths/documents-findByDate.yaml"
+  /documents/findByMention/{docID}:
+    $ref: "./openapi/paths/documents-findByMention.yaml"
+  /documents/findByAuthor/{authorID}:
+    $ref: "./openapi/paths/documents-findByAuthor.yaml"
+  /code/findByElement/{element}:
+    $ref: "./openapi/paths/code-findByElement.yaml"
+  /application/status:
+    $ref: "./openapi/paths/application-status.yaml"
+  /application/newID:
+    $ref: "./openapi/paths/application-newID.yaml"
+  /facets/{facet}:
+    $ref: "./openapi/paths/facets.yaml"
+components:
+  schemas:
+    Document:
+      $ref: "./openapi/schemas/document.yaml"
+    CodeSample:
+      $ref: "./openapi/schemas/codeSample.yaml"
+    Facet:
+      $ref: "./openapi/schemas/facet.yaml"
+    Repository:
+      $ref: "./openapi/schemas/repository.yaml"
+    Item:
+      $ref: "./openapi/schemas/item.yaml"
+    Error:
+      $ref: "./openapi/schemas/error.yaml"
+  parameters:
+    offsetParam:
+      $ref: "./openapi/parameters/offset.yaml"
+    limitParam:
+      $ref: "./openapi/parameters/limit.yaml"
+    fromDateParam:
+      $ref: "./openapi/parameters/fromDate.yaml"
+    toDateParam:
+      $ref: "./openapi/parameters/toDate.yaml"
+    qParam:
+      $ref: "./openapi/parameters/q.yaml"
+    docTypeParam:
+      $ref: "./openapi/parameters/docType.yaml"

api/v1/openapi/parameters/docType.yaml

@@ -0,0 +1,8 @@
+# docType parameter
+name: docType
+in: query
+description: The WeGA document type
+style: form
+explode: false
+schema:
+  $ref: '../schemas/docTypes.yaml'

api/v1/openapi/parameters/docTypeRequired.yaml

@@ -0,0 +1,9 @@
+# docType parameter
+name: docType
+in: query
+description: The WeGA document type
+required: true
+style: form
+explode: false
+schema:
+  $ref: '../schemas/docTypes.yaml'

api/v1/openapi/parameters/fromDate.yaml

@@ -0,0 +1,7 @@
+# fromDate parameter
+name: fromDate
+in: query
+description: The earliest date
+schema:
+  type: string
+  format: date

api/v1/openapi/parameters/limit.yaml

@@ -0,0 +1,9 @@
+# limit parameter
+name: limit
+in: query
+description: Number of items to retrieve (200 max)
+schema:
+  maximum: 200
+  type: integer
+  format: int32
+  default: 10

api/v1/openapi/parameters/offset.yaml

@@ -0,0 +1,9 @@
+# offset parameter
+name: offset
+in: query
+description: Position of first item to retrieve (starting from 1)
+schema:
+  minimum: 1
+  type: integer
+  format: int32
+  default: 1

api/v1/openapi/parameters/q.yaml

@@ -0,0 +1,6 @@
+# q parameter
+name: q
+in: query
+description: The query string
+schema:
+  type: string

api/v1/openapi/parameters/toDate.yaml

@@ -0,0 +1,7 @@
+# toDate parameter
+name: toDate
+in: query
+description: The latest date
+schema:
+  type: string
+  format: date

api/v1/openapi/paths/application-newID.yaml

@@ -0,0 +1,37 @@
+# /application/newID path
+get:
+  tags:
+    - Application
+  summary: Create a new WeGA ID
+  parameters:
+    - $ref: '../parameters/docTypeRequired.yaml'
+  responses:
+    200:
+      description: A single object with a fresh WeGA ID
+      content:
+        application/json:
+          schema:
+            type: object
+            properties:
+              docID:
+                pattern: '^A[A-F0-9]{6}$'
+                type: string
+                description: The WeGA ID
+              docType:
+                type: string
+                description: The WeGA document type
+    403:
+      description: The creation of new IDs is only available in the development environment
+      content:
+        application/json:
+          schema:
+            type: object
+            properties:
+              code:
+                type: integer
+                format: int32
+                default: 403
+              message:
+                type: string
+    default:
+      $ref: '../responses/unexpectedError.yaml'

api/v1/openapi/paths/application-status.yaml

@@ -0,0 +1,50 @@
+# /application/status path
+get:
+  tags:
+    - Application
+  summary: Get status information about the running WeGA-WebApp
+  responses:
+    '200':
+      description: Healthy – A single object with status information
+      content:
+        application/json:
+          schema:
+            type: object
+            properties:
+              status:
+                type: string
+                description: Status (healthy|unhealthy) of the currently running WeGA-WebApp
+                default: healthy
+              svnRevision:
+                type: integer
+                description: The Subversion revision of the currently installed WeGA-data
+              deployment:
+                type: string
+                description: The datetime of the deployment of the WeGA-WebApp
+                format: date-time
+              version:
+                pattern: ^\d+\.\d+\.\d+$
+                type: string
+    '500':
+      description: Unhealthy – A single object with status information
+      content:
+        application/json:
+          schema:
+            type: object
+            properties:
+              status:
+                type: string
+                description: Status (healthy|unhealthy) of the currently running WeGA-WebApp
+                default: unhealthy
+              svnRevision:
+                type: integer
+                description: The Subversion revision of the currently installed WeGA-data
+              deployment:
+                type: string
+                description: The datetime of the deployment of the WeGA-WebApp
+                format: date-time
+              version:
+                pattern: ^\d+\.\d+\.\d+$
+                type: string
+    default:
+      $ref: '../responses/unexpectedError.yaml'

api/v1/openapi/paths/code-findByElement.yaml

@@ -0,0 +1,37 @@
+# /code/findByElement/{element} path
+get:
+  tags:
+    - Code Samples
+  summary: Finds code samples by XML element
+  parameters:
+    - name: element
+      in: path
+      description: The XML element to search for
+      required: true
+      schema:
+        type: string
+    - name: namespace
+      in: query
+      description: The element namespace. Defaults to the TEI namespace
+      schema:
+        type: string
+        default: 'http://www.tei-c.org/ns/1.0'
+    - $ref: '../parameters/docType.yaml'
+    - $ref: '../parameters/offset.yaml'
+    - $ref: '../parameters/limit.yaml'
+  responses:
+    '200':
+      description: An array of documents
+      headers:
+        totalrecordcount:
+          description: The total size of the result set
+          schema:
+            type: integer
+      content:
+        application/json:
+          schema:
+            type: array
+            items:
+              $ref: '../schemas/codeSample.yaml'
+    default:
+      $ref: '../responses/unexpectedError.yaml'

api/v1/openapi/paths/documents-docID.yaml

@@ -0,0 +1,27 @@
+# /documents/{docID} path
+get:
+  tags:
+    - Documents
+  summary: Returns documents by ID
+  description: |
+    This endpoint returns documents, indicated by an ID.
+     Accepted ID formats are WeGA, e.g. A002068 or http://weber-gesamtausgabe.de/A002068, VIAF, e.g. http://viaf.org/viaf/14959938, Wikidata, e.g. http://www.wikidata.org/entity/Q154812, or GND, e.g. http://d-nb.info/gnd/118629662
+  parameters:
+    - name: docID
+      in: path
+      description: The document identifier to search for
+      required: true
+      schema:
+        type: string
+        default: A002068
+  responses:
+    '200':
+      description: An array of documents
+      content:
+        application/json:
+          schema:
+            type: array
+            items:
+              $ref: '../schemas/document.yaml'
+    default:
+      $ref: '../responses/unexpectedError.yaml'

api/v1/openapi/paths/documents-findByAuthor.yaml

@@ -0,0 +1,35 @@
+# /documents/findByAuthor/{authorID} path
+get:
+  tags:
+    - Documents
+  summary: Finds documents by author
+  description: |
+    This endpoint returns a list of documents by a given author – optionally filtered by document type 
+  parameters:
+    - name: authorID
+      in: path
+      description: |
+        The author ID to search for. Accepted ID formats are WeGA, e.g. A002068 or http://weber-gesamtausgabe.de/A002068, VIAF, e.g. http://viaf.org/viaf/14959938, Wikidata, e.g. http://www.wikidata.org/entity/Q154812, or GND, e.g. http://d-nb.info/gnd/118629662
+      required: true
+      schema:
+        type: string
+        default: A002068
+    - $ref: '../parameters/docType.yaml'
+    - $ref: '../parameters/offset.yaml'
+    - $ref: '../parameters/limit.yaml'
+  responses:
+    '200':
+      description: An array of documents
+      headers:
+        totalrecordcount:
+          description: The total size of the result set
+          schema:
+            type: integer
+      content:
+        application/json:
+          schema:
+            type: array
+            items:
+              $ref: '../schemas/document.yaml'
+    default:
+      $ref: '../responses/unexpectedError.yaml'

api/v1/openapi/paths/documents-findByDate.yaml

@@ -0,0 +1,41 @@
+# /documents/findByDate path
+get:
+  tags:
+    - Documents
+  summary: Finds documents by date
+  description: |
+    This endpoint returns a list of documents related to the given date – optionally filtered by document type. 
+  parameters:
+    - name: fromDate
+      in: query
+      description: The min date to search for
+      required: true
+      schema:
+        type: string
+        format: date
+        default: '1786-11-18T00:00:00.000+0000'
+    - name: toDate
+      in: query
+      description: The max date to search for
+      schema:
+        type: string
+        format: date
+    - $ref: '../parameters/docType.yaml'
+    - $ref: '../parameters/offset.yaml'
+    - $ref: '../parameters/limit.yaml'
+  responses:
+    '200':
+      description: An array of documents
+      headers:
+        totalrecordcount:
+          description: The total size of the result set
+          schema:
+            type: integer
+      content:
+        application/json:
+          schema:
+            type: array
+            items:
+              $ref: '../schemas/document.yaml'
+    default:
+      $ref: '../responses/unexpectedError.yaml'