From cc8397bdf12ca5fd02fd3a4fbc194e04fe89e781 Mon Sep 17 00:00:00 2001 From: Erik Lenaerts Date: Thu, 9 Jan 2020 15:28:24 +0100 Subject: [PATCH 1/5] document history en aanpassing van de versie van het document. --- README.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 37342b5..469c47a 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,4 @@ -# Digipolis API design & style requirements v6.0.1 +# Digipolis API design & style requirements v6.0.3 geldig vanaf 01 mei 2019 @@ -96,7 +96,8 @@ Versie | Auteur | Datum | Opmerkingen 5.3.0 | Peter Claes | 05/04/2019 | HTTP methode HEAD. 6.0.0 | Tom Sluyts | 11/04/2019 | Wijziging geolocatie standaard naar geospatiale data standaard. 6.0.1 | Peter Claes | 11/04/2019 | Expliciteren 'description'. -6.0.2 | Peter Claes | 28/10/2019 | Verduidelijking paginatie. +6.0.2 | Erik Lenaerts | 26/09/2019 | Aanpak datetime notatie en tijdzones +6.0.3 | Peter Claes | 28/10/2019 | Verduidelijking paginatie. ## Cheat sheet From 60d1980779e6d17e31a6d899391163a8e4ad532f Mon Sep 17 00:00:00 2001 From: Erik Lenaerts Date: Wed, 22 Apr 2020 13:53:20 +0200 Subject: [PATCH 2/5] add common paging definitions --- paging.yaml | 109 ++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 109 insertions(+) create mode 100644 paging.yaml diff --git a/paging.yaml b/paging.yaml new file mode 100644 index 0000000..a4d372c --- /dev/null +++ b/paging.yaml @@ -0,0 +1,109 @@ +openapi: 3.0.1 +info: + title: Paging + description: In this OAS document we describe the commonly used Paging parameters + as well as the links & pages schema's + version: 1.0.0 +servers: +- url: / +paths: {} +components: + schemas: + Pages: + required: + - number + - size + type: object + properties: + size: + type: integer + description: returns the size of a page provided in the pagesize query parameter + of the request + example: 10 + totalElements: + type: integer + description: the total number of items in the resulting collection + example: 34 + totalPages: + type: integer + description: the total number of pages in the resulting array. This is calculated + with the given size value + example: 4 + number: + type: integer + description: return the page number provided in the page query parameter + of the request + example: 0 + description: A generic model used to describe paging information when requesting + a list of resources. + Links: + type: object + properties: + self: + type: object + properties: + href: + type: string + format: uri + example: https://my-api.digipolis.be/base?pagesize=5&page=2 + description: contains a link to this page of this collection + first: + type: object + properties: + href: + type: string + format: uri + example: https://my-api.digipolis.be/base?pagesize=5&page=0 + description: contains a link to the first page of this collection + last: + type: object + properties: + href: + type: string + format: uri + example: https://my-api.digipolis.be/base?pagesize=5&page=last + description: contains a link to the last page of this collection + prev: + type: object + properties: + href: + type: string + format: uri + example: https://my-api.digipolis.be/base?pagesize=5&page=1 + description: contains a link to the previous page of this collection + next: + type: object + properties: + href: + type: string + format: uri + example: https://my-api.digipolis.be/base?pagesize=5&page=3 + description: contains a link to the next page of this collection + description: provides navigational uri's to other pages of the collection + parameters: + Pagesize: + name: pagesize + in: query + description: Max number of items for each page + required: true + schema: + type: integer + PagingStrategy: + name: paging-strategy + in: query + description: Specify the paging strategy, i.e. if totalPages and totalElements + should be included in the response output + schema: + type: string + default: noCount + enum: + - noCount + - withCount + Page: + name: page + in: query + description: Starting offset for the list, this can be either a number or the + literal "last" + required: true + schema: + type: string From 4c9e9fbb4ce1b42404f67fa8cfea41a45b1d6350 Mon Sep 17 00:00:00 2001 From: Erik Lenaerts Date: Wed, 22 Apr 2020 14:15:35 +0200 Subject: [PATCH 3/5] Add reusable paging definitions --- README.md | 73 ++++++++++++++++++++++++++- paging.yaml => components/paging.yaml | 0 2 files changed, 72 insertions(+), 1 deletion(-) rename paging.yaml => components/paging.yaml (100%) diff --git a/README.md b/README.md index 92f0480..277959f 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,4 @@ -# Digipolis API design & style requirements v6.0.2 +# Digipolis API design & style requirements v6.0.4 geldig vanaf 01 mei 2019 @@ -98,6 +98,7 @@ Versie | Auteur | Datum | Opmerkingen 6.0.1 | Peter Claes | 11/04/2019 | Expliciteren 'description'. 6.0.2 | Erik Lenaerts | 26/09/2019 | Aanpak datetime notatie en tijdzones 6.0.3 | Peter Claes | 28/10/2019 | Verduidelijking paginatie. +6.0.4 | Erik Lenaerts | 22/04/2020 | Herbruikbare definities toegevoegd. ## Cheat sheet @@ -234,6 +235,8 @@ POST [/\]*/\ waarbij \ eindigt op een voltooid deelwoo - template : - template met extra info (opm. geen geldige swagger wegens extrainfo) : - steeds alle descriptions en summaries invullen (in het engels) : routes, parameters, ... : zie ook +- generieke swagger definities voor: + - [paging](paging.yaml) - semantic version opnemen in swagger file ### HTTP verbs @@ -931,6 +934,39 @@ Om de paging strategie mee te geven, gebruikt de consumer de optionele parameter Bij **`withCount`** worden __`Totaal aantal elementen`__ en __`Totaal aantal pagina's`__ altijd verplicht terug gegeven. Bovendien bevat de __`link naar de laatste pagina`__ het paginanummer (zie verder voor een voorbeeld). Bij **`noCount`** worden de beide totalen niet terug gegeven en is de link naar de laatste pagina een link zonder paginanummer met de vermelding **`last`** (zie verder voor een voorbeeld). +> Om je te helpen hebben we de definitie van `page`, `pagesize` en `paging-strategy` reeds gemaakt voor jou in de [paging.yaml swagger](paging.yaml) file. In onderstaand voorbeeld tonen we hoe je hier gebruik van kan maken: + +```JSON + "paths": { + "/invoices": { + "get": { + "summary": "Retrieve a list of invoices", + "description": "Retrieve a paged result list of Sales Invoices", + "parameters": [ + { + "$ref": "https://raw.githubusercontent.com/digipolisantwerpdocumentation/api-requirements/components/paging.yaml#/components/parameters/Page" + }, + { + "$ref": "https://raw.githubusercontent.com/digipolisantwerpdocumentation/api-requirements/components/paging.yaml#/components/parameters/Pagesize" + }, + { + "$ref": "https://raw.githubusercontent.com/digipolisantwerpdocumentation/api-requirements/components/paging.yaml#/components/parameters/PagingStrategy" + }, + { + ... + } + ], + } + } + } +``` + +Herbruikbare definities van oa. pagingatie parameters vind je terug in de [/components](/components) map hier op GitHub. Om er vanuit jouw swagger file ernaar te refereren kan je volgende link gebruiken: + +`https://raw.githubusercontent.com/digipolisantwerpdocumentation/api-requirements/components/paging.yaml#/components/parameters/Page` + +Vervang daar waar nodig het deel achter de `#` in deze url. + ### Paginatie response bericht Om paginatie informatie naar de consumer terug te sturen baseren we ons op de HAL specificatie: @@ -989,6 +1025,10 @@ Dit alles resulteert in volgende structuur in de response message om pagina link } ``` +**Tip:** Net zoals de `page` en `pagesize` parameter, hebben we deze `_links` data structuur definitie ook reeds voorgemaakt op: + +`https://raw.githubusercontent.com/digipolisantwerpdocumentation/api-requirements/components/paging.yaml#/components/schema/Links` + Bij het ophalen van collections dient bovenstaande structuur steeds aanwezig te zijn in een response message. Dit maakt dat de eigenlijke resources in een wrapper object komen te zitten in het response bericht. Dit kan door middel van het **\_embedded** reserved keyword. Dit \_embedded object bestaat uit property namen dewelke een link relation type voorstellen en wiens waarde 1 of meerdere resource objecten zijn. @@ -1029,6 +1069,11 @@ Voorbeeld bij `paging-strategy=noCount` : } ``` +**Tip:** Deze `_page` data structuur definitie is reeds voorgemaakt op: + +`https://raw.githubusercontent.com/digipolisantwerpdocumentation/api-requirements/components/paging.yaml#/components/schema/Page` + + Alle aspecten van paginatie samenvoegend geeft dit volgende response wrapper message voor paginatie: ```json { @@ -1106,6 +1151,32 @@ Geeft als resultaat } ``` +De swagger voor bovenstaand voorbeeld gebruik makende van de generieke definities ziet er als volgt uit: + +```JSON + "MyResources": { + "type": "object", + "properties": { + "_links": { + "$ref": "https://raw.githubusercontent.com/digipolisantwerpdocumentation/api-requirements/components/paging.yaml#/components/schema/Links" + }, + "_embedded": { + "type": "object", + "properties": { + "business-parties": { + "type": "array", + "items": { + ... + } + } + } + }, + "_page": { + "$ref": "https://raw.githubusercontent.com/digipolisantwerpdocumentation/api-requirements/components/paging.yaml#/components/schema/Page" + } + +``` + Het ophalen van business parties (noCount) ``` prettyprint diff --git a/paging.yaml b/components/paging.yaml similarity index 100% rename from paging.yaml rename to components/paging.yaml From 7e4a2de73f930ef55e92a99829937e37d4883535 Mon Sep 17 00:00:00 2001 From: Erik Lenaerts Date: Wed, 22 Apr 2020 14:20:38 +0200 Subject: [PATCH 4/5] fix typos --- README.md | 10 +++------- 1 file changed, 3 insertions(+), 7 deletions(-) diff --git a/README.md b/README.md index 277959f..45a14aa 100644 --- a/README.md +++ b/README.md @@ -934,7 +934,7 @@ Om de paging strategie mee te geven, gebruikt de consumer de optionele parameter Bij **`withCount`** worden __`Totaal aantal elementen`__ en __`Totaal aantal pagina's`__ altijd verplicht terug gegeven. Bovendien bevat de __`link naar de laatste pagina`__ het paginanummer (zie verder voor een voorbeeld). Bij **`noCount`** worden de beide totalen niet terug gegeven en is de link naar de laatste pagina een link zonder paginanummer met de vermelding **`last`** (zie verder voor een voorbeeld). -> Om je te helpen hebben we de definitie van `page`, `pagesize` en `paging-strategy` reeds gemaakt voor jou in de [paging.yaml swagger](paging.yaml) file. In onderstaand voorbeeld tonen we hoe je hier gebruik van kan maken: +> Om je te helpen hebben we de definitie van **`page`**, **`pagesize`** en **`paging-strategy`** reeds gemaakt voor jou in de [paging.yaml swagger](/components/paging.yaml) file. In onderstaand voorbeeld tonen we hoe je hier gebruik van kan maken: ```JSON "paths": { @@ -951,9 +951,6 @@ Bij **`noCount`** worden de beide totalen niet terug gegeven en is de link naar }, { "$ref": "https://raw.githubusercontent.com/digipolisantwerpdocumentation/api-requirements/components/paging.yaml#/components/parameters/PagingStrategy" - }, - { - ... } ], } @@ -1025,7 +1022,7 @@ Dit alles resulteert in volgende structuur in de response message om pagina link } ``` -**Tip:** Net zoals de `page` en `pagesize` parameter, hebben we deze `_links` data structuur definitie ook reeds voorgemaakt op: +**Tip:** Net zoals de **`page`** en **`pagesize`** parameter, hebben we deze **_links** data structuur definitie ook reeds voorgemaakt op: `https://raw.githubusercontent.com/digipolisantwerpdocumentation/api-requirements/components/paging.yaml#/components/schema/Links` @@ -1069,7 +1066,7 @@ Voorbeeld bij `paging-strategy=noCount` : } ``` -**Tip:** Deze `_page` data structuur definitie is reeds voorgemaakt op: +**Tip:** Deze **_page** data structuur definitie is reeds voorgemaakt op: `https://raw.githubusercontent.com/digipolisantwerpdocumentation/api-requirements/components/paging.yaml#/components/schema/Page` @@ -1166,7 +1163,6 @@ De swagger voor bovenstaand voorbeeld gebruik makende van de generieke definitie "business-parties": { "type": "array", "items": { - ... } } } From 3ca6dec5e352c268fa9e946f9e57ebb0d44582f9 Mon Sep 17 00:00:00 2001 From: Erik Lenaerts Date: Thu, 18 Jun 2020 10:50:34 +0200 Subject: [PATCH 5/5] adding more predefined swagger snippets that can be reused --- components/paging.yaml | 5 +- components/problem.yaml | 109 ++++++++++++++++++++++++++++++++++++++++ 2 files changed, 112 insertions(+), 2 deletions(-) create mode 100644 components/problem.yaml diff --git a/components/paging.yaml b/components/paging.yaml index a4d372c..8d3e4f6 100644 --- a/components/paging.yaml +++ b/components/paging.yaml @@ -31,9 +31,10 @@ components: example: 4 number: type: integer + minimum: 1 description: return the page number provided in the page query parameter of the request - example: 0 + example: 1 description: A generic model used to describe paging information when requesting a list of resources. Links: @@ -53,7 +54,7 @@ components: href: type: string format: uri - example: https://my-api.digipolis.be/base?pagesize=5&page=0 + example: https://my-api.digipolis.be/base?pagesize=5&page=1 description: contains a link to the first page of this collection last: type: object diff --git a/components/problem.yaml b/components/problem.yaml new file mode 100644 index 0000000..fbcfd44 --- /dev/null +++ b/components/problem.yaml @@ -0,0 +1,109 @@ +openapi: 3.0.1 +info: + title: problem types + version: 1.0.0 +servers: +- url: / +paths: {} +components: + schemas: + Problem: + type: object + properties: + type: + type: string + description: A URI identifying this problem. The URI should resolve into + human-readable documentation for this problem. + format: uri + example: http://api-gateway/digipolis/payment/v1/payments/FE0032 + 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: You do not have enough credit. + status: + maximum: 6E+2 + exclusiveMaximum: true + minimum: 4E+2 + type: integer + description: The HTTP status code generated by the origin server for this + occurrence of the problem. + format: int32 + example: 400 + identifier: + type: string + description: a unique identifier of the given problem, usefull to recover + this problem message into a logging system. + example: C5C68BE6-B5FF-11E5-B08F-D1D119563991 + code: + type: string + description: the code of the given problem + example: FE0032 + description: A generic model used to describe problems as a result of incorrect + or failed HTTP requests . + ExtraInfoProblem: + description: Problem with extra information + allOf: + - $ref: '#/components/schemas/Problem' + - type: object + properties: + extraInfo: + type: string + description: extra information regarding the problem + InvalidParamProblem: + description: Problem details for invalid input parameter(s) + allOf: + - $ref: '#/components/schemas/Problem' + - type: object + properties: + invalidParams: + type: array + description: An array of parameter OpenAPI violations + items: + $ref: '#/components/schemas/InvalidParam' + InvalidParam: + type: object + properties: + in: + type: string + description: The location of the invalid parameter (cfr Swagger parameters) + enum: + - body + - path + - query + - header + name: + type: string + description: The name of the invalid parameter + reason: + type: string + description: A message explaining the violation + value: + type: object + description: The value of the erroneous parameter + responses: + BadRequest: + description: Bad request + content: + application/problem+json: + schema: + $ref: '#/components/schemas/Problem' + Unexpected: + description: Unexpected error + content: + application/problem+json: + schema: + $ref: '#/components/schemas/Problem' + InternalServer: + description: Internal Server Error + content: + application/problem+json: + schema: + $ref: '#/components/schemas/Problem' + NotFound: + description: Not found + content: + application/problem+json: + schema: + $ref: '#/components/schemas/Problem'