govuk_tech_docs 2.2.0 → 2.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4adec245cbbc73fe2a14f73eb4a0eb2f9acf4d8d751f0786271c59f479c8b244
-  data.tar.gz: 9017c133a8dace561bf56b4e2ec852b4dcdc15a341501b8784659f229f2f183a
+  metadata.gz: 61743fbb0930f511a18a3e9640a85d0f7646c0e4ad8f3c0c1007db3ca27ed571
+  data.tar.gz: a5c775c15afb940c17f730f43b571d791aa208b84b8372219fb130b83aae6d4b
 SHA512:
-  metadata.gz: 3da0c05902288480bf1953b7d5ad275742707cb8324cebe68a1f970cb9dda1b2c70a6538aa9af7a6272973e4b08b3a10108ad6591cbb78bae5aa4e46d436357d
-  data.tar.gz: 1ca0540c1625e80f25d89426f893d15368da0c13b84e5824c4808abd62bfed7bf1e4b93738c2ecd76fe43d70fd23b5517494078ab94367f062f4a73f8c0cec8f
+  metadata.gz: 801d7d5ea6af33e7d8921e88c505649c37552da4e46dae3708d928515aa0dae7d8dfeb4785b602134580354c2acd0bd12c6b7338dbff592dc0559414d6fa1032
+  data.tar.gz: 43c8d28ab4a4ebcfb176b164304c6c36310934c0a71bef2cdb3fd18007d8320cfd0d518ab75f12cba3579408420d0ff77d1827a5cb29fe310400159e40c30320

data/CHANGELOG.md

@@ -1,5 +1,10 @@
 # Changelog
 
+## 2.2.1
+
+- [#218: Remove unnecessary explicit dependencies: sprockets, activesupport, sass and pry](https://github.com/alphagov/tech-docs-gem/pull/218)
+- [#125: Fix API docs showing required properties as optional](https://github.com/alphagov/tech-docs-gem/pull/125)
+
 ## 2.2.0
 
 ### Accessibility Fixes
@@ -100,7 +105,6 @@ You can look at the [2.0.6 milestone](https://github.com/alphagov/tech-docs-gem/
 
 ## 2.0.5
 
-
 Adds [new global configuration option](https://github.com/alphagov/tech-docs-gem/pull/122) that controls whether review banners appear or not at the bottom of pages when expiry dates are set in the frontmatter.
 
 [Fixes the hard-coded service link](https://github.com/alphagov/tech-docs-gem/pull/119) in the header.

data/govuk_tech_docs.gemspec

@@ -32,7 +32,6 @@ Gem::Specification.new do |spec|
   spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
   spec.require_paths = ["lib"]
 
-  spec.add_dependency "activesupport"
   spec.add_dependency "chronic", "~> 0.10.2"
   spec.add_dependency "middleman", "~> 4.0"
   spec.add_dependency "middleman-autoprefixer", "~> 2.10.0"
@@ -42,14 +41,9 @@ Gem::Specification.new do |spec|
   spec.add_dependency "middleman-sprockets", "~> 4.0.0"
   spec.add_dependency "middleman-syntax", "~> 3.2.0"
   spec.add_dependency "nokogiri"
-  spec.add_dependency "openapi3_parser", "~> 0.5.0"
-  spec.add_dependency "pry"
+  spec.add_dependency "openapi3_parser", "~> 0.9.0"
   spec.add_dependency "redcarpet", "~> 3.5.0"
-  spec.add_dependency "sass"
-  spec.add_dependency "sprockets", "~> 4.0.0"
 
-
-  spec.add_development_dependency "bundler", "~> 2.2.0"
   spec.add_development_dependency "byebug"
   spec.add_development_dependency "capybara", "~> 3.32"
   spec.add_development_dependency "jasmine", "~> 3.5.0"

data/lib/govuk_tech_docs/api_reference/api_reference_extension.rb

@@ -1,7 +1,6 @@
 require "erb"
 require "openapi3_parser"
 require "uri"
-require "pry"
 require "govuk_tech_docs/api_reference/api_reference_renderer"
 
 module GovukTechDocs

data/lib/govuk_tech_docs/api_reference/api_reference_renderer.rb

@@ -18,20 +18,15 @@ module GovukTechDocs
       end
 
       def api_full(info, servers)
-        paths = ""
-        paths_data = @document.paths
-        paths_data.each do |path_data|
-          # For some reason paths.each returns an array of arrays [title, object]
-          # instead of an array of objects
-          text = path_data[0]
-          paths += path(text)
+        paths = @document.paths.keys.inject("") do |memo, text|
+          memo + path(text)
         end
-        schemas = ""
-        schemas_data = @document.components.schemas
-        schemas_data.each do |schema_data|
-          text = schema_data[0]
-          schemas += schema(text)
+
+        schema_names = @document.components.schemas.keys
+        schemas = schema_names.inject("") do |memo, schema_name|
+          memo + schema(schema_name)
         end
+
         @template_api_full.result(binding)
       end
 
@@ -42,128 +37,78 @@ module GovukTechDocs
         @template_path.result(binding)
       end
 
-      def schema(text)
-        schemas = ""
-        schemas_data = @document.components.schemas
-        schemas_data.each do |schema_data|
-          all_of = schema_data[1]["allOf"]
-          properties = []
-          if !all_of.blank?
-            all_of.each do |schema_nested|
-              schema_nested.properties.each do |property|
-                properties.push property
-              end
-            end
-          end
+      def schema(title)
+        schema = @document.components.schemas[title]
+        return unless schema
 
-          schema_data[1].properties.each do |property|
-            properties.push property
-          end
+        properties = if schema.all_of
+                       schema.all_of.each_with_object({}) do |nested, memo|
+                         memo.merge!(nested.properties.to_h)
+                       end
+                     else
+                       {}
+                     end
 
-          if schema_data[0] == text
-            title = schema_data[0]
-            schema = schema_data[1]
-            return @template_schema.result(binding)
-          end
-        end
+        properties.merge!(schema.properties.to_h)
+        @template_schema.result(binding)
       end
 
       def schemas_from_path(text)
-        path = @document.paths[text]
-        operations = get_operations(path)
-        # Get all referenced schemas
-        schemas = []
-        operations.compact.each_value do |operation|
-          responses = operation.responses
-          responses.each do |_rkey, response|
-            if response.content["application/json"]
-              schema = response.content["application/json"].schema
-              schema_name = get_schema_name(schema.node_context.source_location.to_s)
-              if !schema_name.nil?
-                schemas.push schema_name
-              end
-              schemas.concat(schemas_from_schema(schema))
-            end
+        operations = get_operations(@document.paths[text])
+        schemas = operations.flat_map do |_, operation|
+          operation.responses.inject([]) do |memo, (_, response)|
+            next memo unless response.content["application/json"]
+
+            schema = response.content["application/json"].schema
+
+            memo << schema.name if schema.name
+            memo + schemas_from_schema(schema)
           end
         end
+
         # Render all referenced schemas
-        output = ""
-        schemas.uniq.each do |schema_name|
-          output += schema(schema_name)
-        end
-        if !output.empty?
-          output.prepend('<h2 id="schemas">Schemas</h2>')
+        output = schemas.uniq.inject("") do |memo, schema_name|
+          memo + schema(schema_name)
         end
+
+        output.prepend('<h2 id="schemas">Schemas</h2>') unless output.empty?
         output
       end
 
       def schemas_from_schema(schema)
-        schemas = []
-        properties = []
-        schema.properties.each do |property|
-          properties.push property[1]
-        end
-        if schema.type == "array"
-          properties.push schema.items
-        end
-        all_of = schema["allOf"]
-        if !all_of.blank?
-          all_of.each do |schema_nested|
-            schema_nested.properties.each do |property|
-              properties.push property[1]
-            end
-          end
-        end
-        properties.each do |property|
-          # Must be a schema be referenced by another schema
-          # And not a property of a schema
-          if property.node_context.referenced_by.to_s.include?("#/components/schemas") &&
-              !property.node_context.source_location.to_s.include?("/properties/")
-            schema_name = get_schema_name(property.node_context.source_location.to_s)
-          end
-          if !schema_name.nil?
-            schemas.push schema_name
-          end
-          # Check sub-properties for references
-          schemas.concat(schemas_from_schema(property))
+        schemas = schema.properties.map(&:last)
+        schemas << schema.items if schema.items && schema.type == "array"
+        schemas += schema.all_of.to_a.flat_map { |s| s.properties.map(&:last) }
+
+        schemas.flat_map do |nested|
+          sub_schemas = schemas_from_schema(nested)
+          nested.name ? [nested.name] + sub_schemas : sub_schemas
         end
-        schemas
       end
 
       def operations(path, path_id)
-        output = ""
-        operations = get_operations(path)
-        operations.compact.each do |key, operation|
+        get_operations(path).inject("") do |memo, (key, operation)|
           id = "#{path_id}-#{key.parameterize}"
           parameters = parameters(operation, id)
           responses = responses(operation, id)
-          output += @template_operation.result(binding)
+          memo + @template_operation.result(binding)
         end
-        output
       end
 
       def parameters(operation, operation_id)
         parameters = operation.parameters
         id = "#{operation_id}-parameters"
-        output = @template_parameters.result(binding)
-        output
+        @template_parameters.result(binding)
       end
 
       def responses(operation, operation_id)
         responses = operation.responses
         id = "#{operation_id}-responses"
-        output = @template_responses.result(binding)
-        output
-      end
-
-      def markdown(text)
-        if text
-          Tilt["markdown"].new(context: @app) { text }.render
-        end
+        @template_responses.result(binding)
       end
 
       def json_output(schema)
-        properties =  schema_properties(schema)
+        properties = schema_properties(schema)
         JSON.pretty_generate(properties)
       end
 
@@ -172,76 +117,26 @@ module GovukTechDocs
       end
 
       def schema_properties(schema_data)
-        properties = Hash.new
-        if defined? schema_data.properties
-          schema_data.properties.each do |key, property|
-            properties[key] = property
-          end
-        end
-        properties.merge! get_all_of_hash(schema_data)
-        properties_hash = Hash.new
-        properties.each do |pkey, property|
-          if property.type == "object"
-            properties_hash[pkey] = Hash.new
-            items = property.items
-            if !items.blank?
-              properties_hash[pkey] = schema_properties(items)
-            end
-            if !property.properties.blank?
-              properties_hash[pkey] = schema_properties(property)
-            end
-          elsif property.type == "array"
-            properties_hash[pkey] = Array.new
-            items = property.items
-            if !items.blank?
-              properties_hash[pkey].push schema_properties(items)
-            end
-          else
-            properties_hash[pkey] = !property.example.nil? ? property.example : property.type
-          end
-        end
-
-        properties_hash
-      end
-
-    private
+        properties = schema_data.properties.to_h
 
-      def get_all_of_array(schema)
-        properties = Array.new
-        if schema.is_a?(Array)
-          schema = schema[1]
-        end
-        if schema["allOf"]
-          all_of = schema["allOf"]
-        end
-        if !all_of.blank?
-          all_of.each do |schema_nested|
-            schema_nested.properties.each do |property|
-              if property.is_a?(Array)
-                property = property[1]
-              end
-              properties.push property
-            end
-          end
+        schema_data.all_of.to_a.each do |all_of_schema|
+          properties.merge!(all_of_schema.properties.to_h)
         end
-        properties
-      end
 
-      def get_all_of_hash(schema)
-        properties = Hash.new
-        if schema["allOf"]
-          all_of = schema["allOf"]
-        end
-        if !all_of.blank?
-          all_of.each do |schema_nested|
-            schema_nested.properties.each do |key, property|
-              properties[key] = property
-            end
-          end
+        properties.each_with_object({}) do |(name, schema), memo|
+          memo[name] = case schema.type
+                       when "object"
+                         schema_properties(schema.items || schema)
+                       when "array"
+                         schema.items ? [schema_properties(schema.items)] : []
+                       else
+                         schema.example || schema.type
+                       end
         end
-        properties
       end
 
+    private
+
       def get_renderer(file)
         template_path = File.join(File.dirname(__FILE__), "templates/" + file)
         template = File.open(template_path, "r").read
@@ -249,31 +144,20 @@ module GovukTechDocs
       end
 
       def get_operations(path)
-        operations = {}
-        operations["get"] = path.get if defined? path.get
-        operations["put"] = path.put if defined? path.put
-        operations["post"] = path.post if defined? path.post
-        operations["delete"] = path.delete if defined? path.delete
-        operations["patch"] = path.patch if defined? path.patch
-        operations
-      end
-
-      def get_schema_name(text)
-        unless text.is_a?(String)
-          return nil
-        end
-
-        # Schema dictates that it's always components['schemas']
-        text.gsub(/#\/components\/schemas\//, "")
+        {
+          "get" => path.get,
+          "put" => path.put,
+          "post" => path.post,
+          "delete" => path.delete,
+          "patch" => path.patch,
+        }.compact
       end
 
       def get_schema_link(schema)
-        schema_name = get_schema_name schema.node_context.source_location.to_s
-        if !schema_name.nil?
-          id = "schema-#{schema_name.parameterize}"
-          output = "<a href='\##{id}'>#{schema_name}</a>"
-          output
-        end
+        return unless schema.name
+
+        id = "schema-#{schema.name.parameterize}"
+        "<a href='\##{id}'>#{schema.name}</a>"
       end
     end
   end

data/lib/govuk_tech_docs/api_reference/templates/api_reference_full.html.erb

@@ -1,7 +1,8 @@
 <h1 id="<%=  info.title.parameterize %>"><%= info.title %> v<%= info.version %></h1>
-<%= markdown(info.description) %>
+<%= info.description_html %>
 
-<% unless servers.empty? %>
+<%# OpenAPI files default to having a single server of URL "/" %>
+<% if servers.length > 1 || servers[0].url != "/" %>
   <h2 id="servers">Servers</h2>
   <div id="server-list">
     <% servers.each do |server| %>

data/lib/govuk_tech_docs/api_reference/templates/operation.html.erb

@@ -3,7 +3,7 @@
   <p><em><%= operation.summary %></em></p>
 <% end %>
 <% if operation.description %>
-  <p><%= markdown(operation.description) %></p>
+  <%= operation.description_html %>
 <% end %>
 
 <%= parameters %>

data/lib/govuk_tech_docs/api_reference/templates/parameters.html.erb

@@ -11,7 +11,7 @@
 <td><%= parameter.in %></td>
 <td><%= parameter.schema.type %></td>
 <td><%= parameter.required? %></td>
-<td><%= markdown(parameter.description) %>
+<td><%= parameter.description_html %>
 <% if parameter.schema.enum %>
 <p>Available items:</p>
 <ul>

data/lib/govuk_tech_docs/api_reference/templates/responses.html.erb

@@ -9,7 +9,7 @@
 <tr>
 <td><%= key %></td>
 <td>
-<%= markdown(response.description) %>
+<%= response.description_html %>
 <% if response.content['application/json']
 if response.content['application/json']["example"]
   request_body = json_prettyprint(response.content['application/json']["example"])

data/lib/govuk_tech_docs/api_reference/templates/schema.html.erb

@@ -1,26 +1,26 @@
 <h3 id="<%= id = 'schema-' + title; id.parameterize %>"><%= title %></h3>
-<%= markdown(schema.description) %>
+<%= schema.description_html %>
 <% if properties.any? %>
-<table>
+<table class='<%= id.parameterize %>'>
 <thead>
 <tr><th>Name</th><th>Type</th><th>Required</th><th>Description</th><th>Schema</th></tr>
 </thead>
 <tbody>
-<% properties.each do |property| %>
+<% properties.each do |property_name, property_attributes| %>
 <tr>
-<td><%= property[0] %></td>
-<td><%= property[1].type %></td>
-<td><%= property[1].required.present? %></td>
-<td><%= markdown(property[1].description) %></td>
+<td><%= property_name %></td>
+<td><%= property_attributes.type %></td>
+<td><%= schema.requires?(property_name) %></td>
+<td><%= property_attributes.description_html %></td>
 <td>
   <%=
-  schema = property[1]
+  linked_schema = property_attributes
   # If property is an array, check the items property for a reference.
-  if property[1].type == 'array'
-    schema = property[1]['items']
+  if property_attributes.type == 'array'
+    linked_schema = property_attributes['items']
   end
-  # Only print a link if it's a referenced object.
-  get_schema_link(schema) if schema.node_context.referenced_by.to_s.include? '#/components/schemas' and !schema.node_context.source_location.to_s.include? '/properties/' %>
+  # Only print a link if it's a named schema
+  get_schema_link(linked_schema) if linked_schema.name %>
 </td>
 </tr>
 <% end %>

data/lib/govuk_tech_docs/version.rb

@@ -1,3 +1,3 @@
 module GovukTechDocs
-  VERSION = "2.2.0".freeze
+  VERSION = "2.2.1".freeze
 end

metadata

@@ -1,29 +1,15 @@
 --- !ruby/object:Gem::Specification
 name: govuk_tech_docs
 version: !ruby/object:Gem::Version
-  version: 2.2.0
+  version: 2.2.1
 platform: ruby
 authors:
 - Government Digital Service
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2021-03-12 00:00:00.000000000 Z
+date: 2021-03-15 00:00:00.000000000 Z
 dependencies:
-- !ruby/object:Gem::Dependency
-  name: activesupport
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
-  type: :runtime
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
 - !ruby/object:Gem::Dependency
   name: chronic
   requirement: !ruby/object:Gem::Requirement
@@ -156,28 +142,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.5.0
+        version: 0.9.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.5.0
-- !ruby/object:Gem::Dependency
-  name: pry
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
-  type: :runtime
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
+        version: 0.9.0
 - !ruby/object:Gem::Dependency
   name: redcarpet
   requirement: !ruby/object:Gem::Requirement
@@ -192,48 +164,6 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: 3.5.0
-- !ruby/object:Gem::Dependency
-  name: sass
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
-  type: :runtime
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
-- !ruby/object:Gem::Dependency
-  name: sprockets
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: 4.0.0
-  type: :runtime
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: 4.0.0
-- !ruby/object:Gem::Dependency
-  name: bundler
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: 2.2.0
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: 2.2.0
 - !ruby/object:Gem::Dependency
   name: byebug
   requirement: !ruby/object:Gem::Requirement