[api] [wip] Swagger-based API doc

api/ui_api.swagger.yaml

@@ -0,0 +1,132 @@
+openapi: 3.0.3
+info:
+  title: Zorg op Orde API
+  description: |-
+    Copyright Zorg op Orde – All rights reserved.
+    
+    Security is done, for now, via cookies - i.e. just make the API request,
+    if done from a browser session that is logged in, the API request is handled.
+    
+    All API requests can return an error state of 'not logged in' or 'not authorized'
+    (which means, some user is logged in, but is not allowed to see / act the thing they want to see / act on).
+  contact:
+    name: Zorg op Orde tech lead
+    email: r.zwitserloot@zorgoporde.nl
+  version: 0.1-DEV
+externalDocs:
+  description: Find out more about Swagger
+  url: http://swagger.io
+servers:
+  - url: https://tools.zorgoporde.nl/api1
+    description: Production
+  - url: https://test.zorgoporde.nl/api1
+    description: Testing
+tags:
+  - name: core
+    description: |-
+      Functionality that cross-cuts API concerns, such as authentication.
+      TBD.
+
+  - name: QoC
+    description: |-
+      API related to Quality of Care features
+      
+      A care program (dutch: _ketenzorg_ or _zorgprogramma_) describes a specific disease (such as Diabetes or Astma) or a more abstract concern such as elderly care or 
+general concern about cardiovascular health. The same care program can show up multiple times, as there are different care programs and standards for the same disease or 
+concern. For example, there could be the InEen report 'take' on how one should provide Diabetes care, and there could be some regional group's slightly different take on it; 
+these would show up as different care programs.
+
+      Any given customer has a 'fave' status for any given care program; some care programs are enabled by default and some are disabled by default. However, a customer can 
+explicitly select a program they wouldn't ordinarily see ('favourite' it), or explicitly deselect a program they get by default ('unfavourite' it). Most care programs will 
+be neither favourited nor unfavourited: They should be shown based on their `default_show` property.
+
+      To allow favouriting/unfavouriting, the front end has 2 separate views for selecting care programs: The usual view, which shows _only_:
+      - Care programs that customer has explicitly favourited.
+      - Care programs that are shown by default to this customer which they did not explicitly unfavourite.
+
+      As well as a 'config' view where they see _all_ care programs that could possibly be relevant for that customer, where the customer can preview the report 
+(essentially, run the report as normal), favourite something they don't get by default, or unfavourite something they get by default.
+paths:
+  /qoc/careprogram/list:
+    get:
+      tags:
+        - QoC
+      summary: List all available care programs
+      description: Includes all care programs that the user is allowed to see, even ones that are unfavourited or not shown by default.
+      responses:
+        '200':
+          description: Success
+          content:
+            application/json:
+              schema:
+                type: array
+                items: 
+                  $ref: '#/components/schemas/CareProgram'
+        '401':
+          $ref: '#/components/responses/NoAuth'
+        '403':
+          $ref: '#/components/responses/NoAccess'
+
+
+components:
+  schemas:
+    CareProgram:
+      type: object
+      properties:
+        name:
+          description: Human readable text in dutch, guaranteed to be quite short.
+          type: string
+          example: Diabetes Mellitus type 2 (ZEL)
+        description:
+          description: in dutch and in *HTML*, can consist of multiple paragraphs, but won't be more than ~5 lines or so.
+          type: string
+          example: Ketenzorg DM2 volgens de standaard werkwijze van zorgggroep ZEL.
+        default_show:
+          description: If `true`, show this unless explicitly unfavourited. If `false`, do not show unless explicitly favourited.
+          type: boolean
+        fav_state:
+          description: If `T`, always show this. If `F`, never show it. If `X`, show if `default_show` is `true`.
+          type: string
+          example: X
+          enum:
+            - T
+            - F
+            - X
+        reports:
+          description: |-
+            A care program offers 1 or more reports; any given report is generally very different from another.
+            Each offered report should be shown as a button.
+          type: array
+          items:
+            type: object
+            properties:
+              type:
+                oneOf:
+                - description: An indicator set report. use the `/qol/indicatorset` API endpoint.
+                  type: string
+                  example: indicatorset
+                - description: Resolve by loading the URL in the `url` property (`window.location = ` style).
+                  type: string
+                  example: link
+              name:
+                description: Short description in dutch text; show this in the button.
+                type: string
+                example: Indicatoren
+              url:
+                description: >-
+                  Only for `type: "link"`.
+                type: string
+                example: '/indicators/casefinder?t=dm'
+              key:
+                description: >-
+                  Only for `type: "indicatorset"`. Pass to `/qoc/indicatorset` API.
+                type: string
+                example: ZEL-dm2
+
+
+  responses:
+    NoAuth:
+      description: User is not logged in / session expired.
+    NoAccess:
+      description: User is not allowed to access this API endpoint.
+