Separate DFC API swagger config

This allows us to run the specs separately to generate the
documentation. It's more efficient this way and the separate swagger doc
file is easier to read.

The engine-specific swagger helper also allows us to simplify the spec
files.

Added an exception to our styleguide because it's intended and useful to
have a complete (lengthy) description of the API in one block.

.rubocop_styleguide.yml

@@ -25,6 +25,7 @@ Metrics/BlockLength:
   AllowedMethods: [
     "class_eval",
     "collection",
+    "configure",
     "context",
     "delete",
     "describe",

.rubocop_todo.yml

@@ -488,7 +488,6 @@ Metrics/BlockLength:
     - 'app/models/spree/shipment.rb'
     - 'lib/spree/core/controller_helpers/common.rb'
     - 'lib/tasks/data.rake'
-    - 'spec/base_spec_helper.rb'
     - 'spec/factories.rb'
     - 'spec/factories/address_factory.rb'
     - 'spec/factories/enterprise_factory.rb'
@@ -507,7 +506,6 @@ Metrics/BlockLength:
     - 'spec/support/cancan_helper.rb'
     - 'spec/support/matchers/select2_matchers.rb'
     - 'spec/support/matchers/table_matchers.rb'
-    - 'spec/swagger_helper.rb'
     - 'spec/system/consumer/shopping/checkout_spec.rb'
     - 'spec/system/consumer/shopping/checkout_stripe_spec.rb'
     - 'spec/system/consumer/shopping/variant_overrides_spec.rb'

engines/dfc_provider/spec/requests/catalog_items_spec.rb

@@ -1,7 +1,6 @@
 # frozen_string_literal: true
 
-require "swagger_helper"
-require DfcProvider::Engine.root.join("spec/spec_helper")
+require DfcProvider::Engine.root.join("spec/swagger_helper")
 
 describe "CatalogItems", type: :request, swagger_doc: "dfc-v1.7/swagger.yaml",
                          rswag_autodoc: true do

engines/dfc_provider/spec/requests/enterprises_spec.rb

@@ -1,7 +1,6 @@
 # frozen_string_literal: true
 
-require "swagger_helper"
-require DfcProvider::Engine.root.join("spec/spec_helper")
+require DfcProvider::Engine.root.join("spec/swagger_helper")
 
 describe "Enterprises", type: :request, swagger_doc: "dfc-v1.7/swagger.yaml", rswag_autodoc: true do
   let!(:user) { create(:oidc_user) }

engines/dfc_provider/spec/requests/persons_spec.rb

@@ -1,7 +1,6 @@
 # frozen_string_literal: true
 
-require "swagger_helper"
-require DfcProvider::Engine.root.join("spec/spec_helper")
+require DfcProvider::Engine.root.join("spec/swagger_helper")
 
 describe "Persons", type: :request, swagger_doc: "dfc-v1.7/swagger.yaml", rswag_autodoc: true do
   let(:user) { create(:oidc_user, id: 10_000) }

engines/dfc_provider/spec/requests/supplied_products_spec.rb

@@ -1,7 +1,6 @@
 # frozen_string_literal: true
 
-require "swagger_helper"
-require DfcProvider::Engine.root.join("spec/spec_helper")
+require DfcProvider::Engine.root.join("spec/swagger_helper")
 
 describe "SuppliedProducts", type: :request, swagger_doc: "dfc-v1.7/swagger.yaml",
                              rswag_autodoc: true do

engines/dfc_provider/spec/swagger_helper.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+require Rails.root.join("spec/swagger_helper")
+require_relative "spec_helper"
+
+RSpec.configure do |config|
+  # Override swagger docs to generate only this file:
+  config.swagger_docs = {
+    'dfc-v1.7/swagger.yaml' => {
+      openapi: '3.0.1',
+      info: {
+        title: 'OFN DFC API',
+        version: 'v0.1.7'
+      },
+      components: {
+        securitySchemes: {
+          oidc_token: {
+            type: :http,
+            scheme: :bearer,
+            bearerFormat: "JWT",
+            description: "OpenID Connect token from a trusted platform"
+          },
+          ofn_api_token: {
+            type: :apiKey,
+            in: :header,
+            name: 'X-Api-Token',
+            description: "API token of an authorized OFN user"
+          },
+          ofn_session: {
+            type: :apiKey,
+            in: :cookie,
+            name: '_ofn_session',
+            description: "Session cookie of a logged in OFN user"
+          },
+        }
+      },
+      security: [
+        { oidc_token: [] },
+        { ofn_api_token: [] },
+        { ofn_session: [] },
+      ],
+      paths: {},
+      servers: [
+        { url: "/" },
+      ]
+    },
+  }
+end

script/rswag

@@ -1,17 +1,25 @@
-#!/usr/bin/env sh
+#!/usr/bin/env bash
 
 # Generate the API documentation based on our specs.
 #
+# For API v0 and v1 you can call one of these:
+#
+#   ./bin/rake rswag
+#   ./script/rswag --dry-run
+#
+# For the DFC API you need to call:
+#
+#   ./script/rswag engines/dfc_provider
+#
 # The standard way to generate the documentation is `rake rswag` which calls
 # rspec under the hood. We have a few customisations to the rspec call though
 # which only work when calling rspec ourselves.
 #
 # - We actually run the specs to generate examples instead of a dry run.
 #   While rswag has an RSWAG_DRY_RUN switch, it doesn't work with our setup.
-# - We add relevant engines to the pattern.
 # - We run only tagged swagger specs instead of all matching the pattern.
 exec ./bin/rspec\
-  --pattern "spec/requests/api/**/*_spec.rb,engines/dfc_provider/spec/requests/**/*_spec.rb"\
   --tag "swagger_doc"\
   --format "Rswag::Specs::SwaggerFormatter"\
-  --order "defined"
+  --order "defined"\
+  "${@:1}"

spec/swagger_helper.rb

@@ -18,44 +18,6 @@ RSpec.configure do |config|
   # document below. You can override this behavior by adding a swagger_doc tag to the
   # the root example_group in your specs, e.g. describe '...', swagger_doc: 'v2/swagger.json'
   config.swagger_docs = {
-    'dfc-v1.7/swagger.yaml' => {
-      openapi: '3.0.1',
-      info: {
-        title: 'OFN DFC API',
-        version: 'v0.1.7'
-      },
-      components: {
-        securitySchemes: {
-          oidc_token: {
-            type: :http,
-            scheme: :bearer,
-            bearerFormat: "JWT",
-            description: "OpenID Connect token from a trusted platform"
-          },
-          ofn_api_token: {
-            type: :apiKey,
-            in: :header,
-            name: 'X-Api-Token',
-            description: "API token of an authorized OFN user"
-          },
-          ofn_session: {
-            type: :apiKey,
-            in: :cookie,
-            name: '_ofn_session',
-            description: "Session cookie of a logged in OFN user"
-          },
-        }
-      },
-      security: [
-        { oidc_token: [] },
-        { ofn_api_token: [] },
-        { ofn_session: [] },
-      ],
-      paths: {},
-      servers: [
-        { url: "/" },
-      ]
-    },
     'v1/swagger.yaml' => {
       openapi: '3.0.1',
       info: {