From 195c4fc6f31f7b7d7c589740f2c88886e5d23fbf Mon Sep 17 00:00:00 2001 From: Tuomas Suutari Date: Thu, 14 Nov 2019 17:55:34 +0200 Subject: [PATCH 1/8] docs/operator: Convert to openapi 3.0.1 format --- docs/api/operator.yaml | 488 +++++++++++++++++++++-------------------- 1 file changed, 249 insertions(+), 239 deletions(-) diff --git a/docs/api/operator.yaml b/docs/api/operator.yaml index 4c8031a0..a5c18777 100644 --- a/docs/api/operator.yaml +++ b/docs/api/operator.yaml @@ -1,4 +1,4 @@ -swagger: '2.0' +openapi: 3.0.1 info: title: Parkkihubi description: | @@ -7,14 +7,8 @@ info: Authentication: Every request must have header `Authorization: ApiKey ` version: "1.1.0" -host: api.parkkiopas.fi -schemes: - - https -basePath: /operator/v1 -consumes: - - application/json -produces: - - application/json +servers: + - url: https://api.parkkiopas.fi/operator/v1/ paths: /parking/: post: @@ -22,52 +16,54 @@ paths: - parking summary: Create a new parking operationId: createParking - parameters: - - name: parking - in: body - required: true - description: Parking to add to the system - schema: - type: object - example: - location: - type: Point - coordinates: [24.938466, 60.170014] - registration_number: LOL-007 - time_start: "2016-12-24T21:00:00Z" - time_end: "2016-12-24T22:00:00Z" - zone: 2 - properties: - location: - $ref: '#/definitions/Location' - registration_number: - description: Registration number for the parking - type: string - time_start: - description: Start time for the parking - type: string - format: dateTime - time_end: - description: End time for the parking - type: string - format: dateTime - zone: - description: Parking zone - type: integer - enum: [1, 2, 3] - required: - - registration_number - - time_start - - zone + requestBody: + required: true + description: Parking to add to the system + content: + application/json: + schema: + type: object + example: + location: + type: Point + coordinates: [24.938466, 60.170014] + registration_number: LOL-007 + time_start: "2016-12-24T21:00:00Z" + time_end: "2016-12-24T22:00:00Z" + zone: 2 + properties: + location: + $ref: '#/components/schemas/Location' + registration_number: + description: Registration number for the parking + type: string + time_start: + description: Start time for the parking + type: string + format: dateTime + time_end: + description: End time for the parking + type: string + format: dateTime + zone: + description: Parking zone + type: integer + enum: [1, 2, 3] + required: + - registration_number + - time_start + - zone responses: - 201: + '201': description: The parking was created successfully - schema: - $ref: '#/definitions/Parking' - 400: - $ref: '#/responses/BadRequest' - 401: - $ref: '#/responses/Unauthorized' + content: + application/json: + schema: + $ref: '#/components/schemas/Parking' + '400': + $ref: '#/components/responses/BadRequest' + '401': + $ref: '#/components/responses/Unauthorized' /parking/{parking_id}/: put: tags: @@ -79,57 +75,61 @@ paths: in: path required: true description: ID of the parking to update - type: string - format: uuid - - name: parking - in: body - required: true - description: Parking to add to the system schema: - type: object - example: - location: - type: Point - coordinates: [24.938466, 60.170014] - registration_number: LOL-007 - time_start: "2016-12-24T21:00:00Z" - time_end: "2016-12-24T22:00:00Z" - zone: 2 - properties: - location: - $ref: '#/definitions/Location' - registration_number: - description: Registration number for the parking - type: string - time_start: - description: Start time for the parking - type: string - format: dateTime - time_end: - description: End time for the parking - type: string - format: dateTime - zone: - description: Parking zone - type: integer - enum: [1, 2, 3] - required: - - registration_number - - time_start - - zone + type: string + format: uuid + requestBody: + required: true + description: Parking to add to the system + content: + application/json: + schema: + type: object + example: + location: + type: Point + coordinates: [24.938466, 60.170014] + registration_number: LOL-007 + time_start: "2016-12-24T21:00:00Z" + time_end: "2016-12-24T22:00:00Z" + zone: 2 + properties: + location: + $ref: '#/components/schemas/Location' + registration_number: + description: Registration number for the parking + type: string + time_start: + description: Start time for the parking + type: string + format: dateTime + time_end: + description: End time for the parking + type: string + format: dateTime + zone: + description: Parking zone + type: integer + enum: [1, 2, 3] + required: + - registration_number + - time_start + - zone responses: - 200: + '200': description: The parking was updated successfully - schema: - $ref: '#/definitions/Parking' - 400: - $ref: '#/responses/BadRequest' - 401: - $ref: '#/responses/Unauthorized' - 403: - $ref: '#/responses/Forbidden' - 404: - $ref: '#/responses/NotFound' + content: + application/json: + schema: + $ref: '#/components/schemas/Parking' + '400': + $ref: '#/components/responses/BadRequest' + '401': + $ref: '#/components/responses/Unauthorized' + '403': + $ref: '#/components/responses/Forbidden' + '404': + $ref: '#/components/responses/NotFound' patch: tags: - parking @@ -140,47 +140,51 @@ paths: in: path required: true description: ID of the parking to update - type: string - format: uuid - - name: parking - in: body - required: true - description: Parking to add to the system schema: - type: object - example: - time_end: "2016-12-25T22:00:00Z" - properties: - location: - $ref: '#/definitions/Location' - registration_number: - description: Registration number for the parking - type: string - time_start: - description: Start time for the parking - type: string - format: dateTime - time_end: - description: End time for the parking - type: string - format: dateTime - zone: - description: Parking zone - type: integer - enum: [1, 2, 3] + type: string + format: uuid + requestBody: + required: true + description: Parking to add to the system + content: + application/json: + schema: + type: object + example: + time_end: "2016-12-25T22:00:00Z" + properties: + location: + $ref: '#/components/schemas/Location' + registration_number: + description: Registration number for the parking + type: string + time_start: + description: Start time for the parking + type: string + format: dateTime + time_end: + description: End time for the parking + type: string + format: dateTime + zone: + description: Parking zone + type: integer + enum: [1, 2, 3] responses: - 200: + '200': description: The parking was updated successfully - schema: - $ref: '#/definitions/Parking' - 400: - $ref: '#/responses/BadRequest' - 401: - $ref: '#/responses/Unauthorized' - 403: - $ref: '#/responses/Forbidden' - 404: - $ref: '#/responses/NotFound' + content: + application/json: + schema: + $ref: '#/components/schemas/Parking' + '400': + $ref: '#/components/responses/BadRequest' + '401': + $ref: '#/components/responses/Unauthorized' + '403': + $ref: '#/components/responses/Forbidden' + '404': + $ref: '#/components/responses/NotFound' delete: tags: - parking @@ -191,110 +195,116 @@ paths: in: path required: true description: ID of the parking to delete - type: string - format: uuid + schema: + type: string + format: uuid responses: - 204: + '204': description: The parking was deleted successfully - 401: - $ref: '#/responses/Unauthorized' - 403: - $ref: '#/responses/Forbidden' - 404: - $ref: '#/responses/NotFound' -definitions: - Parking: - type: object - example: - id: 70fb01a8-a17f-4b14-9b99-0060c748411c - status: valid - created_at: "2016-12-10T20:34:38Z" - modified_at: "2016-12-11T21:34:22Z" - location: - type: Point - coordinates: [24.938466, 60.170014] - registration_number: LOL-007 - time_start: "2016-12-24T21:00:00Z" - time_end: "2016-12-24T22:00:00Z" - zone: 2 - properties: - id: - description: Unique identifier for the parking - type: string - format: uuid - readOnly: true - status: - description: Status of the parking - type: string - enum: [valid, not_valid] - readOnly: true - created_at: - description: Creation time for the parking - type: string - format: dateTime - readOnly: true - modified_at: - description: Modification time for the parking - type: string - format: dateTime - readOnly: true - location: - $ref: '#/definitions/Location' - registration_number: - description: Registration number for the parking - type: string - time_start: - description: Start time for the parking - type: string - format: dateTime - time_end: - description: End time for the parking - type: string - format: dateTime - zone: - description: Parking zone - type: integer - enum: [1, 2, 3] - required: - - registration_number - - time_start - - zone - Location: - description: Point location in geoJSON format - type: object - example: - type: Point - coordinates: [24.938466, 60.170014] - properties: - type: - description: Location geometry type. - type: string - coordinates: - description: An array of coordinates describing the location geometry (longitude, latitude) - type: array - items: - type: number - format: float -responses: - BadRequest: - description: Bad request, details in request body - schema: - example: - registration_number: [Enter a valid value.] - Unauthorized: - description: Unauthorized access - Forbidden: - description: Forbidden request - schema: + '401': + $ref: '#/components/responses/Unauthorized' + '403': + $ref: '#/components/responses/Forbidden' + '404': + $ref: '#/components/responses/NotFound' +components: + schemas: + Parking: type: object + example: + id: 70fb01a8-a17f-4b14-9b99-0060c748411c + status: valid + created_at: "2016-12-10T20:34:38Z" + modified_at: "2016-12-11T21:34:22Z" + location: + type: Point + coordinates: [24.938466, 60.170014] + registration_number: LOL-007 + time_start: "2016-12-24T21:00:00Z" + time_end: "2016-12-24T22:00:00Z" + zone: 2 properties: - code: + id: + description: Unique identifier for the parking + type: string + format: uuid + readOnly: true + status: + description: Status of the parking + type: string + enum: [valid, not_valid] + readOnly: true + created_at: + description: Creation time for the parking + type: string + format: dateTime + readOnly: true + modified_at: + description: Modification time for the parking + type: string + format: dateTime + readOnly: true + location: + $ref: '#/components/schemas/Location' + registration_number: + description: Registration number for the parking type: string - enum: [unknown_error, permission_denied, grace_period_over] - detail: + time_start: + description: Start time for the parking type: string + format: dateTime + time_end: + description: End time for the parking + type: string + format: dateTime + zone: + description: Parking zone + type: integer + enum: [1, 2, 3] + required: + - registration_number + - time_start + - zone + Location: + description: Point location in geoJSON format + type: object example: - code: grace_period_over - detail: Grace period has passed. Only "time_end" can be updated via PATCH. - NotFound: - description: Parking not found + type: Point + coordinates: [24.938466, 60.170014] + properties: + type: + description: Location geometry type. + type: string + coordinates: + description: An array of coordinates describing the location geometry (longitude, latitude) + type: array + items: + type: number + format: float + responses: + BadRequest: # 400 + description: Bad request, details in request body + content: + application/json: + schema: + example: + registration_number: [Enter a valid value.] + Unauthorized: # 401 + description: Unauthorized access + Forbidden: # 403 + description: Forbidden request + content: + application/json: + schema: + type: object + properties: + code: + type: string + enum: [unknown_error, permission_denied, grace_period_over] + detail: + type: string + example: + code: grace_period_over + detail: Grace period has passed. Only "time_end" can be updated via PATCH. + NotFound: # 404 + description: Parking not found From a742653986e2eda526442359d61792fabcaf3183 Mon Sep 17 00:00:00 2001 From: Tuomas Suutari Date: Thu, 14 Nov 2019 17:55:57 +0200 Subject: [PATCH 2/8] docs/operator: Add security schemes --- docs/api/operator.yaml | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/docs/api/operator.yaml b/docs/api/operator.yaml index a5c18777..fb7cab80 100644 --- a/docs/api/operator.yaml +++ b/docs/api/operator.yaml @@ -16,6 +16,7 @@ paths: - parking summary: Create a new parking operationId: createParking + security: [{ApiKey: []}] requestBody: required: true description: Parking to add to the system @@ -70,6 +71,7 @@ paths: - parking summary: Update a parking by its ID operationId: updateParkingById + security: [{ApiKey: []}] parameters: - name: parking_id in: path @@ -135,6 +137,7 @@ paths: - parking summary: Partial update a parking by its ID operationId: partialUpdateParkingById + security: [{ApiKey: []}] parameters: - name: parking_id in: path @@ -190,6 +193,7 @@ paths: - parking summary: Delete a parking by its ID operationId: deleteParkingById + security: [{ApiKey: []}] parameters: - name: parking_id in: path @@ -208,6 +212,11 @@ paths: '404': $ref: '#/components/responses/NotFound' components: + securitySchemes: + ApiKey: + type: apiKey + name: Authorization + in: header schemas: Parking: type: object From 07ca96a62f59faaef065167a4b1b2f7be8075b81 Mon Sep 17 00:00:00 2001 From: Tuomas Suutari Date: Thu, 14 Nov 2019 17:57:11 +0200 Subject: [PATCH 3/8] docs/operator: Update title and description --- docs/api/operator.yaml | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/docs/api/operator.yaml b/docs/api/operator.yaml index fb7cab80..a31bb068 100644 --- a/docs/api/operator.yaml +++ b/docs/api/operator.yaml @@ -1,11 +1,12 @@ openapi: 3.0.1 info: - title: Parkkihubi - description: | - Parkkihubi REST API Documentation (Operator) + title: Parkkihubi Operator API + description: >- + Parkkihubi Operator REST API Documentation - Authentication: Every request must have header `Authorization: ApiKey ` + Authentication: Every request must have header: + Authorization: ApiKey version: "1.1.0" servers: - url: https://api.parkkiopas.fi/operator/v1/ From a0120cd0205a335d1475f18a0a7ca6e2c2aa2597 Mon Sep 17 00:00:00 2001 From: Tuomas Suutari Date: Thu, 14 Nov 2019 17:57:42 +0200 Subject: [PATCH 4/8] docs/operator: Add test and development API urls --- docs/api/operator.yaml | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/docs/api/operator.yaml b/docs/api/operator.yaml index a31bb068..dc14032b 100644 --- a/docs/api/operator.yaml +++ b/docs/api/operator.yaml @@ -10,6 +10,11 @@ info: version: "1.1.0" servers: - url: https://api.parkkiopas.fi/operator/v1/ + description: Production server + - url: https://testapi.parkkiopas.fi/operator/v1/ + description: Test server + - url: http://localhost:8000/operator/v1/ + description: Local development server paths: /parking/: post: From b41970527d249f00f744ac61b40b87976af692f3 Mon Sep 17 00:00:00 2001 From: Tuomas Suutari Date: Thu, 14 Nov 2019 17:57:55 +0200 Subject: [PATCH 5/8] docs/operator: Improve tags --- docs/api/operator.yaml | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/docs/api/operator.yaml b/docs/api/operator.yaml index dc14032b..6d89397b 100644 --- a/docs/api/operator.yaml +++ b/docs/api/operator.yaml @@ -15,11 +15,14 @@ servers: description: Test server - url: http://localhost:8000/operator/v1/ description: Local development server +tags: + - name: Parkings + description: >- + Endpoints for creating and updating parkings paths: /parking/: post: - tags: - - parking + tags: ['Parkings'] summary: Create a new parking operationId: createParking security: [{ApiKey: []}] @@ -73,8 +76,7 @@ paths: $ref: '#/components/responses/Unauthorized' /parking/{parking_id}/: put: - tags: - - parking + tags: ['Parkings'] summary: Update a parking by its ID operationId: updateParkingById security: [{ApiKey: []}] @@ -139,8 +141,7 @@ paths: '404': $ref: '#/components/responses/NotFound' patch: - tags: - - parking + tags: ['Parkings'] summary: Partial update a parking by its ID operationId: partialUpdateParkingById security: [{ApiKey: []}] @@ -195,8 +196,7 @@ paths: '404': $ref: '#/components/responses/NotFound' delete: - tags: - - parking + tags: ['Parkings'] summary: Delete a parking by its ID operationId: deleteParkingById security: [{ApiKey: []}] From 656d903913d92b29d125cfd0fa0b1f7cfeda509c Mon Sep 17 00:00:00 2001 From: Tuomas Suutari Date: Fri, 15 Nov 2019 07:45:24 +0200 Subject: [PATCH 6/8] docs/operator: Add terminal_number field The terminal_number field was added to parking endpoints long time ago (in commit 5a4b289c6ba), but was forgotten from the documentation. --- docs/api/operator.yaml | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/docs/api/operator.yaml b/docs/api/operator.yaml index 6d89397b..c408e16e 100644 --- a/docs/api/operator.yaml +++ b/docs/api/operator.yaml @@ -44,6 +44,12 @@ paths: properties: location: $ref: '#/components/schemas/Location' + terminal_number: + description: >- + Payment terminal number, if the parking was bought + from a payment terminal. + type: string + default: '' registration_number: description: Registration number for the parking type: string @@ -261,6 +267,12 @@ components: readOnly: true location: $ref: '#/components/schemas/Location' + terminal_number: + description: >- + Payment terminal number, if the parking was bought + from a payment terminal. + type: string + default: '' registration_number: description: Registration number for the parking type: string From 02dd7f9eefdc622c2d8b0717ad60e6d6eccc7f93 Mon Sep 17 00:00:00 2001 From: Tuomas Suutari Date: Fri, 15 Nov 2019 10:30:57 +0200 Subject: [PATCH 7/8] docs/operator: Improve "location" GeoJSON spec --- docs/api/operator.yaml | 11 ++++++++--- 1 file changed, 8 insertions(+), 3 deletions(-) diff --git a/docs/api/operator.yaml b/docs/api/operator.yaml index c408e16e..9939abf1 100644 --- a/docs/api/operator.yaml +++ b/docs/api/operator.yaml @@ -293,18 +293,23 @@ components: - time_start - zone Location: - description: Point location in geoJSON format + description: Location in GeoJSON format type: object example: type: Point coordinates: [24.938466, 60.170014] properties: type: - description: Location geometry type. + description: Geometry type type: string + enum: [Point] coordinates: - description: An array of coordinates describing the location geometry (longitude, latitude) + description: >- + An array of coordinates describing the location geometry. + The items are WGS84 longitude and latitude in that order. type: array + minItems: 2 + maxItems: 2 items: type: number format: float From b82965cbc0285a59088f7f2a369d7101af11a09f Mon Sep 17 00:00:00 2001 From: Tuomas Suutari Date: Fri, 15 Nov 2019 10:38:26 +0200 Subject: [PATCH 8/8] docs/operator: Fix payment zone descriptions --- docs/api/operator.yaml | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/api/operator.yaml b/docs/api/operator.yaml index 9939abf1..0c3b0bb1 100644 --- a/docs/api/operator.yaml +++ b/docs/api/operator.yaml @@ -62,7 +62,7 @@ paths: type: string format: dateTime zone: - description: Parking zone + description: Payment zone type: integer enum: [1, 2, 3] required: @@ -124,7 +124,7 @@ paths: type: string format: dateTime zone: - description: Parking zone + description: Payment zone type: integer enum: [1, 2, 3] required: @@ -183,7 +183,7 @@ paths: type: string format: dateTime zone: - description: Parking zone + description: Payment zone type: integer enum: [1, 2, 3] responses: @@ -285,7 +285,7 @@ components: type: string format: dateTime zone: - description: Parking zone + description: Payment zone type: integer enum: [1, 2, 3] required: