Class: FtrRuby::OpenAPI

Inherits:
Object
  • Object
show all
Defined in:
lib/openapi.rb

Overview

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.

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(meta:) ⇒ OpenAPI

Initialises the OpenAPI document from a metadata hash.

Parameters:

  • meta (Hash) —

    keys: :testid, :testname, :testversion, :metric, :description, :indicators, :organization, :org_url, :responsible_developer, :email, :creator, :host, :protocol, :basePath, :response_description, :schemas



24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
 
# File 'lib/openapi.rb', line 24

def initialize(meta:)
  indics = [meta[:indicators]] unless meta[:indicators].is_a? Array
  @testid = meta[:testid]
  @title = meta[:testname]
  @version = meta[:testversion]
  @metric = meta[:metric]
  @description = meta[:description]
  @indicator = indics.first
  @organization = meta[:organization]
  @org_url = meta[:org_url]
  @responsible_developer = meta[:responsible_developer]
  @email = meta[:email]
  @creator = meta[:creator]
  @host =  meta[:host]
  @host = @host.gsub(%r{/$}, "") # remove trailing slash if present
  @protocol =  meta[:protocol].gsub(%r{[:/]}, "")
  @basePath =  meta[:basePath].gsub(%r{[:/]}, "")
  @basePath = "/#{basePath}" unless basePath[0] == "/" # must start with a slash
  # @path = meta[:path]
  @response_description = meta[:response_description]
  @schemas = meta[:schemas]
  @endpointpath = "assess/test"
  # @end_url = "#{protocol}://#{host}#{basePath}/#{endpointpath}/#{testid}" # basepath starts with /
end

Instance Attribute Details

#basePath ⇒ Object

Returns the value of attribute basePath.



14
15
16
 
# File 'lib/openapi.rb', line 14

def basePath
  @basePath
end

#creator ⇒ Object

Returns the value of attribute creator.



14
15
16
 
# File 'lib/openapi.rb', line 14

def creator
  @creator
end

#description ⇒ Object

Returns the value of attribute description.



14
15
16
 
# File 'lib/openapi.rb', line 14

def description
  @description
end

#developer_ORCiD ⇒ Object

Returns the value of attribute developer_ORCiD.



14
15
16
 
# File 'lib/openapi.rb', line 14

def developer_ORCiD
  @developer_ORCiD
end

#email ⇒ Object

Returns the value of attribute email.



14
15
16
 
# File 'lib/openapi.rb', line 14

def email
  @email
end

#endpointpath ⇒ Object

Returns the value of attribute endpointpath.



14
15
16
 
# File 'lib/openapi.rb', line 14

def endpointpath
  @endpointpath
end

#host ⇒ Object

Returns the value of attribute host.



14
15
16
 
# File 'lib/openapi.rb', line 14

def host
  @host
end

#indicator ⇒ Object

Returns the value of attribute indicator.



14
15
16
 
# File 'lib/openapi.rb', line 14

def indicator
  @indicator
end

#metric ⇒ Object

Returns the value of attribute metric.



14
15
16
 
# File 'lib/openapi.rb', line 14

def metric
  @metric
end

#org_url ⇒ Object

Returns the value of attribute org_url.



14
15
16
 
# File 'lib/openapi.rb', line 14

def org_url
  @org_url
end

#organization ⇒ Object

Returns the value of attribute organization.



14
15
16
 
# File 'lib/openapi.rb', line 14

def organization
  @organization
end

#path ⇒ Object

Returns the value of attribute path.



14
15
16
 
# File 'lib/openapi.rb', line 14

def path
  @path
end

#protocol ⇒ Object

Returns the value of attribute protocol.



14
15
16
 
# File 'lib/openapi.rb', line 14

def protocol
  @protocol
end

#response_description ⇒ Object

Returns the value of attribute response_description.



14
15
16
 
# File 'lib/openapi.rb', line 14

def response_description
  @response_description
end

#responsible_developer ⇒ Object

Returns the value of attribute responsible_developer.



14
15
16
 
# File 'lib/openapi.rb', line 14

def responsible_developer
  @responsible_developer
end

#schemas ⇒ Object

Returns the value of attribute schemas.



14
15
16
 
# File 'lib/openapi.rb', line 14

def schemas
  @schemas
end

#testid ⇒ Object

Returns the value of attribute testid.



14
15
16
 
# File 'lib/openapi.rb', line 14

def testid
  @testid
end

#title ⇒ Object

Returns the value of attribute title.



14
15
16
 
# File 'lib/openapi.rb', line 14

def title
  @title
end

#version ⇒ Object

Returns the value of attribute version.



14
15
16
 
# File 'lib/openapi.rb', line 14

def version
  @version
end

Instance Method Details

#get_api ⇒ Object

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.



54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
 
# File 'lib/openapi.rb', line 54

def get_api
  safe_desc = yaml_block_indent(description, 4)
  safe_resp = yaml_block_indent(response_description, 12)
  <<~"EOF_EOF"

    openapi: 3.0.0
    info:
      version: "#{version}"
      title: "#{title}"
      x-tests_metric: "#{metric}"
      description: >-
        #{safe_desc}
      x-applies_to_principle: "#{indicator}"
      contact:
        x-organization: "#{organization}"
        url: "#{org_url}"
        name: "#{responsible_developer}"
        x-role: responsible developer
        email: "#{email}"
        x-id: "#{creator}"
    paths:
      "/#{testid}":
        post:
          requestBody:
            content:
              application/json:
                schema:
                  $ref: "#/components/schemas/schemas"
            required: true
          responses:
            "200":
              description:  >-
                #{safe_resp}
    servers:
      - url: "#{protocol}://#{host}#{basePath}/#{endpointpath}"
    components:
      schemas:
        schemas:
          required:
            - resource_identifier
          properties:
            resource_identifier:
              type: string
              description: the GUID being tested

  EOF_EOF
end