From a38b7b4191715f95c47432d4362258bc35293c0c Mon Sep 17 00:00:00 2001 From: Reinier Zwitserloot Date: Mon, 3 Apr 2023 03:57:56 +0200 Subject: [PATCH] [api] [wip] Swagger-based API doc --- api/ui_api.swagger.yaml | 132 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 132 insertions(+) create mode 100644 api/ui_api.swagger.yaml diff --git a/api/ui_api.swagger.yaml b/api/ui_api.swagger.yaml new file mode 100644 index 0000000..91dc940 --- /dev/null +++ b/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. +