Correct OFN session cookie name

And improve the documentation in general.

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
-```

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,
+        <p>
+        This API implements the Data Food Consortium (DFC) specifications.
+        It serves and reads semantic data encoded in JSON-LD.
+        <p>
+        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:
+              <ul>
+                <li><a href="https://login.lescommuns.org/auth/" target="_blank">Les Communs</a></li>
+              </ul>
+            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
           },
         }
       },

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"
           },

swagger/dfc-v1.7/swagger.yaml

@@ -3,13 +3,23 @@ openapi: 3.0.1
 info:
   title: OFN DFC API
   version: v0.1.7
+description: |
+  <p>
+  This API implements the Data Food Consortium (DFC) specifications.
+  It serves and reads semantic data encoded in JSON-LD.
+  <p>
+  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:
+        <ul>
+          <li><a href="https://login.lescommuns.org/auth/" target="_blank">Les Communs</a></li>
+        </ul>
     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: []

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: