ftr_ruby 0.1.9 → 0.1.10

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5fad967881ddfedcde26bbeb0866164d3648ddb01f79f5deb7ab011fc5d12ffb
-  data.tar.gz: d8a29cba7c2b4eff908fdf878826c31a54f73c6375a8561d3074906ddd8efa46
+  metadata.gz: e667a36034df0b5e34edc576681737cb36d010ad54ae6f71a9254823438ddf0e
+  data.tar.gz: 48b56876e75bc26dd80c430f9a0e242538895aa239e5290ebbdd77253010bb64
 SHA512:
-  metadata.gz: 7e28a1b1e8c3a4b66e2a263e8111747bd42c739fb3169f754d07de3e51ca5d3bbf01bcc264e9d10331584525014d1b2cfd41a1f4d231432ddc5cd7f692e6f3bd
-  data.tar.gz: c0ba5c7ee46a2355008283e977f2284103cd25ccda4feb6d0bf0117b8489d5bcb7d32d6337be30d8530a9622a628ec1962d9a919e7c78f16ecd3690c6a7abb46
+  metadata.gz: c26ebde15b974102fbf169f7d4a60118cdde56ceaa041306f5edf8c81f8c260b0deb389b1e36d9e7a5fbd4c11ca7e2f729dfdbd24bf59560a82f8c62d5f8de1a
+  data.tar.gz: 6c5746418ab0aba173c1cd8f975ecaf71b4df961cc365570873d795b75d6ee414080ab2c78a253f3c4c58e07a713bc2800b4d0ce806659628749b2c7ef124568

data/lib/ftr_ruby/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module FtrRuby
-  VERSION = "0.1.9"
+  VERSION = "0.1.10"
 end

data/lib/openapi.rb

@@ -1,10 +1,26 @@
 module FtrRuby
+  # Generates a valid OpenAPI 3.0 YAML document describing a single FAIR test endpoint.
+  #
+  # The document is built from metadata supplied by the test author (title, description,
+  # contact info, etc.) and is served as a machine-readable API specification that client
+  # UIs fetch to dynamically build submission forms.
+  #
+  # Key concern: author-supplied text (especially +description+) may contain arbitrary
+  # Markdown, including blank lines and heading markers (##).  YAML block scalars require
+  # every continuation line to be indented at least as deeply as the first content line;
+  # raw multi-line strings break this rule.  All free-text fields are therefore passed
+  # through +yaml_block_indent+ before interpolation.
   class OpenAPI
     attr_accessor :title, :metric, :description, :indicator, :testid,
                   :organization, :org_url, :version, :creator,
                   :responsible_developer, :email, :developer_ORCiD, :protocol,
                   :host, :basePath, :path, :response_description, :schemas, :endpointpath
 
+    # Initialises the OpenAPI document from a metadata hash.
+    #
+    # @param meta [Hash] keys: :testid, :testname, :testversion, :metric, :description,
+    #   :indicators, :organization, :org_url, :responsible_developer, :email, :creator,
+    #   :host, :protocol, :basePath, :response_description, :schemas
     def initialize(meta:)
       indics = [meta[:indicators]] unless meta[:indicators].is_a? Array
       @testid = meta[:testid]
@@ -30,7 +46,14 @@ module FtrRuby
       # @end_url = "#{protocol}://#{host}#{basePath}/#{endpointpath}/#{testid}" # basepath starts with /
     end
 
+    # Returns the complete OpenAPI 3.0 YAML document as a String.
+    #
+    # Free-text fields that may contain Markdown (description, response_description) are
+    # pre-processed with +yaml_block_indent+ so that embedded newlines do not escape the
+    # YAML block scalar — see that method for details.
     def get_api
+      safe_desc = yaml_block_indent(description, 4)
+      safe_resp = yaml_block_indent(response_description, 12)
       <<~"EOF_EOF"
 
         openapi: 3.0.0
@@ -39,7 +62,7 @@ module FtrRuby
           title: "#{title}"
           x-tests_metric: "#{metric}"
           description: >-
-            #{description}
+            #{safe_desc}
           x-applies_to_principle: "#{indicator}"
           contact:
             x-organization: "#{organization}"
@@ -60,7 +83,7 @@ module FtrRuby
               responses:
                 "200":
                   description:  >-
-                    #{response_description}
+                    #{safe_resp}
         servers:
           - url: "#{protocol}://#{host}#{basePath}/#{endpointpath}"
         components:
@@ -75,5 +98,29 @@ module FtrRuby
 
       EOF_EOF
     end
+
+    private
+
+    # Ensures a multi-line string is safe for use inside a YAML block scalar (>- or |).
+    #
+    # YAML block scalars determine their indentation level from the first content line.
+    # Any subsequent line that is indented less than that level terminates the scalar,
+    # which causes parse errors when the text contains blank lines followed by
+    # unindented content (a common pattern in Markdown).
+    #
+    # This method leaves the first line untouched (the heredoc template already places
+    # it at the correct column) and prepends +spaces+ spaces to every non-empty
+    # continuation line so they remain inside the block scalar.  Blank lines are left
+    # blank intentionally — YAML allows empty lines within a block scalar without
+    # requiring indentation.
+    #
+    # @param text   [String]  the raw author-supplied text
+    # @param spaces [Integer] number of spaces matching the block scalar's indentation
+    #   in the rendered YAML (4 for +description+, 12 for +response_description+)
+    # @return [String]
+    def yaml_block_indent(text, spaces)
+      indent = " " * spaces
+      text.split("\n").map.with_index { |line, i| i.zero? || line.empty? ? line : "#{indent}#{line}" }.join("\n")
+    end
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ftr_ruby
 version: !ruby/object:Gem::Version
-  version: 0.1.9
+  version: 0.1.10
 platform: ruby
 authors:
 - markwilkinson