From 811740c3614fec01bb4fd1d4d3213635a0766bee Mon Sep 17 00:00:00 2001 From: Maikel Linke Date: Fri, 30 Jun 2023 16:38:06 +1000 Subject: [PATCH] Correct OFN session cookie name And improve the documentation in general. --- engines/dfc_provider/README.md | 54 +++++---------------- engines/dfc_provider/spec/swagger_helper.rb | 20 ++++++-- spec/swagger_helper.rb | 2 +- swagger/dfc-v1.7/swagger.yaml | 19 ++++++-- swagger/v1/swagger.yaml | 2 +- 5 files changed, 48 insertions(+), 49 deletions(-) diff --git a/engines/dfc_provider/README.md b/engines/dfc_provider/README.md index f3effcbaac..e8f5771f21 100644 --- a/engines/dfc_provider/README.md +++ b/engines/dfc_provider/README.md @@ -3,45 +3,17 @@ This engine implements the [Data Food Consortium] specifications. It serves and reads semantic data encoded in JSON-LD. +The API is documented with Swagger at `/api-docs`. You can update these docs +with: + +``` +./script/rswag engines/dfc_provider +``` + +More documentation by the Data Food Consortium: + +* https://datafoodconsortium.gitbook.io/dfc-standard-documentation/semantic-specifications/business-ontology +* https://datafoodconsortium.gitbook.io/dfc-standard-documentation/appendixes/practical-examples/version-1.7.3 +* https://github.com/datafoodconsortium/ontology/tree/master/ontologies + [Data Food Consortium]: https://github.com/datafoodconsortium - -## Authentication - -The DFC uses OpenID Connect (OIDC) to authenticate requests. You need an -account with a trusted OIDC provider. Currently these are: - -* https://login.lescommuns.org/auth/ - -But you can also authenticate with your OFN user login (session cookie) through -your browser. - -And you can also use your OFN API token in the HTTP header. For example: - -``` -X-Api-Token: d6ccf8685b8cd29b67ae6186e9ceb423bd2ac30b7c880223 -``` - -## API endpoints - -The API is under development and this list may be out of date. - -``` -/api/dfc-v1.7/persons/:id - * show: firstName, lastName, affiliatedOrganizations - -/api/dfc-v1.7/enterprises/:id - * show: name, suppliedProducts, catalogItems - -/api/dfc-v1.7/enterprises/:enterprise_id/supplied_products (index) - -/api/dfc-v1.7/enterprises/:enterprise_id/supplied_products/:id - * create: name, description, quantity - * show: name, description, productType, quantity - * update: description - -/api/dfc-v1.7/enterprises/:enterprise_id/catalog_items (index) - -/api/dfc-v1.7/enterprises/:enterprise_id/catalog_items/:id - * show: product, sku, stockLimitation, offers (price, stockLimitation) - * update: sku, stockLimitation -``` diff --git a/engines/dfc_provider/spec/swagger_helper.rb b/engines/dfc_provider/spec/swagger_helper.rb index 4dee496e63..7de36d7a64 100644 --- a/engines/dfc_provider/spec/swagger_helper.rb +++ b/engines/dfc_provider/spec/swagger_helper.rb @@ -12,13 +12,25 @@ RSpec.configure do |config| title: 'OFN DFC API', version: 'v0.1.7' }, + description: <<~HTML, +

+ This API implements the Data Food Consortium (DFC) specifications. + It serves and reads semantic data encoded in JSON-LD. +

+ Unfortunately, this description does not appear in the Swagger UI. :-( + HTML components: { securitySchemes: { oidc_token: { type: :http, scheme: :bearer, bearerFormat: "JWT", - description: "OpenID Connect token from a trusted platform" + description: <<~HTML + OpenID Connect token from a trusted platform: +

+ HTML }, ofn_api_token: { type: :apiKey, @@ -29,8 +41,10 @@ RSpec.configure do |config| ofn_session: { type: :apiKey, in: :cookie, - name: '_ofn_session', - description: "Session cookie of a logged in OFN user" + name: '_ofn_session_id', + description: <<~HTML + Session cookie of a logged in user. It allows only read access due to CSRF protection. + HTML }, } }, diff --git a/spec/swagger_helper.rb b/spec/swagger_helper.rb index bebca37075..40baea9c32 100644 --- a/spec/swagger_helper.rb +++ b/spec/swagger_helper.rb @@ -46,7 +46,7 @@ RSpec.configure do |config| }, session: { type: :apiKey, - name: '_ofn_session', + name: '_ofn_session_id', in: :cookie, description: "Authenticates using the current user's session if logged in" }, diff --git a/swagger/dfc-v1.7/swagger.yaml b/swagger/dfc-v1.7/swagger.yaml index 8660bc8943..473bda2f7b 100644 --- a/swagger/dfc-v1.7/swagger.yaml +++ b/swagger/dfc-v1.7/swagger.yaml @@ -3,13 +3,23 @@ openapi: 3.0.1 info: title: OFN DFC API version: v0.1.7 +description: | +

+ This API implements the Data Food Consortium (DFC) specifications. + It serves and reads semantic data encoded in JSON-LD. +

+ Unfortunately, this description does not appear in the Swagger UI. :-( components: securitySchemes: oidc_token: type: http scheme: bearer bearerFormat: JWT - description: OpenID Connect token from a trusted platform + description: | + OpenID Connect token from a trusted platform: +

ofn_api_token: type: apiKey in: header @@ -18,8 +28,11 @@ components: ofn_session: type: apiKey in: cookie - name: _ofn_session - description: Session cookie of a logged in OFN user + name: _ofn_session_id + description: 'Session cookie of a logged in user. It allows only read access + due to CSRF protection. + + ' security: - oidc_token: [] - ofn_api_token: [] diff --git a/swagger/v1/swagger.yaml b/swagger/v1/swagger.yaml index e59001ec0b..a9305be001 100644 --- a/swagger/v1/swagger.yaml +++ b/swagger/v1/swagger.yaml @@ -296,7 +296,7 @@ components: description: Authenticates via API key passed in specified query param session: type: apiKey - name: _ofn_session + name: _ofn_session_id in: cookie description: Authenticates using the current user's session if logged in paths: