govuk_tech_docs 2.2.0 → 2.2.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Potentially problematic release.


This version of govuk_tech_docs might be problematic. Click here for more details.

checksums.yaml CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  SHA256:
3
- metadata.gz: 4adec245cbbc73fe2a14f73eb4a0eb2f9acf4d8d751f0786271c59f479c8b244
4
- data.tar.gz: 9017c133a8dace561bf56b4e2ec852b4dcdc15a341501b8784659f229f2f183a
3
+ metadata.gz: 61743fbb0930f511a18a3e9640a85d0f7646c0e4ad8f3c0c1007db3ca27ed571
4
+ data.tar.gz: a5c775c15afb940c17f730f43b571d791aa208b84b8372219fb130b83aae6d4b
5
5
  SHA512:
6
- metadata.gz: 3da0c05902288480bf1953b7d5ad275742707cb8324cebe68a1f970cb9dda1b2c70a6538aa9af7a6272973e4b08b3a10108ad6591cbb78bae5aa4e46d436357d
7
- data.tar.gz: 1ca0540c1625e80f25d89426f893d15368da0c13b84e5824c4808abd62bfed7bf1e4b93738c2ecd76fe43d70fd23b5517494078ab94367f062f4a73f8c0cec8f
6
+ metadata.gz: 801d7d5ea6af33e7d8921e88c505649c37552da4e46dae3708d928515aa0dae7d8dfeb4785b602134580354c2acd0bd12c6b7338dbff592dc0559414d6fa1032
7
+ data.tar.gz: 43c8d28ab4a4ebcfb176b164304c6c36310934c0a71bef2cdb3fd18007d8320cfd0d518ab75f12cba3579408420d0ff77d1827a5cb29fe310400159e40c30320
data/CHANGELOG.md CHANGED
@@ -1,5 +1,10 @@
1
1
  # Changelog
2
2
 
3
+ ## 2.2.1
4
+
5
+ - [#218: Remove unnecessary explicit dependencies: sprockets, activesupport, sass and pry](https://github.com/alphagov/tech-docs-gem/pull/218)
6
+ - [#125: Fix API docs showing required properties as optional](https://github.com/alphagov/tech-docs-gem/pull/125)
7
+
3
8
  ## 2.2.0
4
9
 
5
10
  ### Accessibility Fixes
@@ -100,7 +105,6 @@ You can look at the [2.0.6 milestone](https://github.com/alphagov/tech-docs-gem/
100
105
 
101
106
  ## 2.0.5
102
107
 
103
-
104
108
  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.
105
109
 
106
110
  [Fixes the hard-coded service link](https://github.com/alphagov/tech-docs-gem/pull/119) in the header.
@@ -32,7 +32,6 @@ Gem::Specification.new do |spec|
32
32
  spec.executables = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
33
33
  spec.require_paths = ["lib"]
34
34
 
35
- spec.add_dependency "activesupport"
36
35
  spec.add_dependency "chronic", "~> 0.10.2"
37
36
  spec.add_dependency "middleman", "~> 4.0"
38
37
  spec.add_dependency "middleman-autoprefixer", "~> 2.10.0"
@@ -42,14 +41,9 @@ Gem::Specification.new do |spec|
42
41
  spec.add_dependency "middleman-sprockets", "~> 4.0.0"
43
42
  spec.add_dependency "middleman-syntax", "~> 3.2.0"
44
43
  spec.add_dependency "nokogiri"
45
- spec.add_dependency "openapi3_parser", "~> 0.5.0"
46
- spec.add_dependency "pry"
44
+ spec.add_dependency "openapi3_parser", "~> 0.9.0"
47
45
  spec.add_dependency "redcarpet", "~> 3.5.0"
48
- spec.add_dependency "sass"
49
- spec.add_dependency "sprockets", "~> 4.0.0"
50
46
 
51
-
52
- spec.add_development_dependency "bundler", "~> 2.2.0"
53
47
  spec.add_development_dependency "byebug"
54
48
  spec.add_development_dependency "capybara", "~> 3.32"
55
49
  spec.add_development_dependency "jasmine", "~> 3.5.0"
@@ -1,7 +1,6 @@
1
1
  require "erb"
2
2
  require "openapi3_parser"
3
3
  require "uri"
4
- require "pry"
5
4
  require "govuk_tech_docs/api_reference/api_reference_renderer"
6
5
 
7
6
  module GovukTechDocs
@@ -18,20 +18,15 @@ module GovukTechDocs
18
18
  end
19
19
 
20
20
  def api_full(info, servers)
21
- paths = ""
22
- paths_data = @document.paths
23
- paths_data.each do |path_data|
24
- # For some reason paths.each returns an array of arrays [title, object]
25
- # instead of an array of objects
26
- text = path_data[0]
27
- paths += path(text)
21
+ paths = @document.paths.keys.inject("") do |memo, text|
22
+ memo + path(text)
28
23
  end
29
- schemas = ""
30
- schemas_data = @document.components.schemas
31
- schemas_data.each do |schema_data|
32
- text = schema_data[0]
33
- schemas += schema(text)
24
+
25
+ schema_names = @document.components.schemas.keys
26
+ schemas = schema_names.inject("") do |memo, schema_name|
27
+ memo + schema(schema_name)
34
28
  end
29
+
35
30
  @template_api_full.result(binding)
36
31
  end
37
32
 
@@ -42,128 +37,78 @@ module GovukTechDocs
42
37
  @template_path.result(binding)
43
38
  end
44
39
 
45
- def schema(text)
46
- schemas = ""
47
- schemas_data = @document.components.schemas
48
- schemas_data.each do |schema_data|
49
- all_of = schema_data[1]["allOf"]
50
- properties = []
51
- if !all_of.blank?
52
- all_of.each do |schema_nested|
53
- schema_nested.properties.each do |property|
54
- properties.push property
55
- end
56
- end
57
- end
40
+ def schema(title)
41
+ schema = @document.components.schemas[title]
42
+ return unless schema
58
43
 
59
- schema_data[1].properties.each do |property|
60
- properties.push property
61
- end
44
+ properties = if schema.all_of
45
+ schema.all_of.each_with_object({}) do |nested, memo|
46
+ memo.merge!(nested.properties.to_h)
47
+ end
48
+ else
49
+ {}
50
+ end
62
51
 
63
- if schema_data[0] == text
64
- title = schema_data[0]
65
- schema = schema_data[1]
66
- return @template_schema.result(binding)
67
- end
68
- end
52
+ properties.merge!(schema.properties.to_h)
53
+ @template_schema.result(binding)
69
54
  end
70
55
 
71
56
  def schemas_from_path(text)
72
- path = @document.paths[text]
73
- operations = get_operations(path)
74
- # Get all referenced schemas
75
- schemas = []
76
- operations.compact.each_value do |operation|
77
- responses = operation.responses
78
- responses.each do |_rkey, response|
79
- if response.content["application/json"]
80
- schema = response.content["application/json"].schema
81
- schema_name = get_schema_name(schema.node_context.source_location.to_s)
82
- if !schema_name.nil?
83
- schemas.push schema_name
84
- end
85
- schemas.concat(schemas_from_schema(schema))
86
- end
57
+ operations = get_operations(@document.paths[text])
58
+ schemas = operations.flat_map do |_, operation|
59
+ operation.responses.inject([]) do |memo, (_, response)|
60
+ next memo unless response.content["application/json"]
61
+
62
+ schema = response.content["application/json"].schema
63
+
64
+ memo << schema.name if schema.name
65
+ memo + schemas_from_schema(schema)
87
66
  end
88
67
  end
68
+
89
69
  # Render all referenced schemas
90
- output = ""
91
- schemas.uniq.each do |schema_name|
92
- output += schema(schema_name)
93
- end
94
- if !output.empty?
95
- output.prepend('<h2 id="schemas">Schemas</h2>')
70
+ output = schemas.uniq.inject("") do |memo, schema_name|
71
+ memo + schema(schema_name)
96
72
  end
73
+
74
+ output.prepend('<h2 id="schemas">Schemas</h2>') unless output.empty?
97
75
  output
98
76
  end
99
77
 
100
78
  def schemas_from_schema(schema)
101
- schemas = []
102
- properties = []
103
- schema.properties.each do |property|
104
- properties.push property[1]
105
- end
106
- if schema.type == "array"
107
- properties.push schema.items
108
- end
109
- all_of = schema["allOf"]
110
- if !all_of.blank?
111
- all_of.each do |schema_nested|
112
- schema_nested.properties.each do |property|
113
- properties.push property[1]
114
- end
115
- end
116
- end
117
- properties.each do |property|
118
- # Must be a schema be referenced by another schema
119
- # And not a property of a schema
120
- if property.node_context.referenced_by.to_s.include?("#/components/schemas") &&
121
- !property.node_context.source_location.to_s.include?("/properties/")
122
- schema_name = get_schema_name(property.node_context.source_location.to_s)
123
- end
124
- if !schema_name.nil?
125
- schemas.push schema_name
126
- end
127
- # Check sub-properties for references
128
- schemas.concat(schemas_from_schema(property))
79
+ schemas = schema.properties.map(&:last)
80
+ schemas << schema.items if schema.items && schema.type == "array"
81
+ schemas += schema.all_of.to_a.flat_map { |s| s.properties.map(&:last) }
82
+
83
+ schemas.flat_map do |nested|
84
+ sub_schemas = schemas_from_schema(nested)
85
+ nested.name ? [nested.name] + sub_schemas : sub_schemas
129
86
  end
130
- schemas
131
87
  end
132
88
 
133
89
  def operations(path, path_id)
134
- output = ""
135
- operations = get_operations(path)
136
- operations.compact.each do |key, operation|
90
+ get_operations(path).inject("") do |memo, (key, operation)|
137
91
  id = "#{path_id}-#{key.parameterize}"
138
92
  parameters = parameters(operation, id)
139
93
  responses = responses(operation, id)
140
- output += @template_operation.result(binding)
94
+ memo + @template_operation.result(binding)
141
95
  end
142
- output
143
96
  end
144
97
 
145
98
  def parameters(operation, operation_id)
146
99
  parameters = operation.parameters
147
100
  id = "#{operation_id}-parameters"
148
- output = @template_parameters.result(binding)
149
- output
101
+ @template_parameters.result(binding)
150
102
  end
151
103
 
152
104
  def responses(operation, operation_id)
153
105
  responses = operation.responses
154
106
  id = "#{operation_id}-responses"
155
- output = @template_responses.result(binding)
156
- output
157
- end
158
-
159
- def markdown(text)
160
- if text
161
- Tilt["markdown"].new(context: @app) { text }.render
162
- end
107
+ @template_responses.result(binding)
163
108
  end
164
109
 
165
110
  def json_output(schema)
166
- properties = schema_properties(schema)
111
+ properties = schema_properties(schema)
167
112
  JSON.pretty_generate(properties)
168
113
  end
169
114
 
@@ -172,76 +117,26 @@ module GovukTechDocs
172
117
  end
173
118
 
174
119
  def schema_properties(schema_data)
175
- properties = Hash.new
176
- if defined? schema_data.properties
177
- schema_data.properties.each do |key, property|
178
- properties[key] = property
179
- end
180
- end
181
- properties.merge! get_all_of_hash(schema_data)
182
- properties_hash = Hash.new
183
- properties.each do |pkey, property|
184
- if property.type == "object"
185
- properties_hash[pkey] = Hash.new
186
- items = property.items
187
- if !items.blank?
188
- properties_hash[pkey] = schema_properties(items)
189
- end
190
- if !property.properties.blank?
191
- properties_hash[pkey] = schema_properties(property)
192
- end
193
- elsif property.type == "array"
194
- properties_hash[pkey] = Array.new
195
- items = property.items
196
- if !items.blank?
197
- properties_hash[pkey].push schema_properties(items)
198
- end
199
- else
200
- properties_hash[pkey] = !property.example.nil? ? property.example : property.type
201
- end
202
- end
203
-
204
- properties_hash
205
- end
206
-
207
- private
120
+ properties = schema_data.properties.to_h
208
121
 
209
- def get_all_of_array(schema)
210
- properties = Array.new
211
- if schema.is_a?(Array)
212
- schema = schema[1]
213
- end
214
- if schema["allOf"]
215
- all_of = schema["allOf"]
216
- end
217
- if !all_of.blank?
218
- all_of.each do |schema_nested|
219
- schema_nested.properties.each do |property|
220
- if property.is_a?(Array)
221
- property = property[1]
222
- end
223
- properties.push property
224
- end
225
- end
122
+ schema_data.all_of.to_a.each do |all_of_schema|
123
+ properties.merge!(all_of_schema.properties.to_h)
226
124
  end
227
- properties
228
- end
229
125
 
230
- def get_all_of_hash(schema)
231
- properties = Hash.new
232
- if schema["allOf"]
233
- all_of = schema["allOf"]
234
- end
235
- if !all_of.blank?
236
- all_of.each do |schema_nested|
237
- schema_nested.properties.each do |key, property|
238
- properties[key] = property
239
- end
240
- end
126
+ properties.each_with_object({}) do |(name, schema), memo|
127
+ memo[name] = case schema.type
128
+ when "object"
129
+ schema_properties(schema.items || schema)
130
+ when "array"
131
+ schema.items ? [schema_properties(schema.items)] : []
132
+ else
133
+ schema.example || schema.type
134
+ end
241
135
  end
242
- properties
243
136
  end
244
137
 
138
+ private
139
+
245
140
  def get_renderer(file)
246
141
  template_path = File.join(File.dirname(__FILE__), "templates/" + file)
247
142
  template = File.open(template_path, "r").read
@@ -249,31 +144,20 @@ module GovukTechDocs
249
144
  end
250
145
 
251
146
  def get_operations(path)
252
- operations = {}
253
- operations["get"] = path.get if defined? path.get
254
- operations["put"] = path.put if defined? path.put
255
- operations["post"] = path.post if defined? path.post
256
- operations["delete"] = path.delete if defined? path.delete
257
- operations["patch"] = path.patch if defined? path.patch
258
- operations
259
- end
260
-
261
- def get_schema_name(text)
262
- unless text.is_a?(String)
263
- return nil
264
- end
265
-
266
- # Schema dictates that it's always components['schemas']
267
- text.gsub(/#\/components\/schemas\//, "")
147
+ {
148
+ "get" => path.get,
149
+ "put" => path.put,
150
+ "post" => path.post,
151
+ "delete" => path.delete,
152
+ "patch" => path.patch,
153
+ }.compact
268
154
  end
269
155
 
270
156
  def get_schema_link(schema)
271
- schema_name = get_schema_name schema.node_context.source_location.to_s
272
- if !schema_name.nil?
273
- id = "schema-#{schema_name.parameterize}"
274
- output = "<a href='\##{id}'>#{schema_name}</a>"
275
- output
276
- end
157
+ return unless schema.name
158
+
159
+ id = "schema-#{schema.name.parameterize}"
160
+ "<a href='\##{id}'>#{schema.name}</a>"
277
161
  end
278
162
  end
279
163
  end
@@ -1,7 +1,8 @@
1
1
  <h1 id="<%= info.title.parameterize %>"><%= info.title %> v<%= info.version %></h1>
2
- <%= markdown(info.description) %>
2
+ <%= info.description_html %>
3
3
 
4
- <% unless servers.empty? %>
4
+ <%# OpenAPI files default to having a single server of URL "/" %>
5
+ <% if servers.length > 1 || servers[0].url != "/" %>
5
6
  <h2 id="servers">Servers</h2>
6
7
  <div id="server-list">
7
8
  <% servers.each do |server| %>
@@ -3,7 +3,7 @@
3
3
  <p><em><%= operation.summary %></em></p>
4
4
  <% end %>
5
5
  <% if operation.description %>
6
- <p><%= markdown(operation.description) %></p>
6
+ <%= operation.description_html %>
7
7
  <% end %>
8
8
 
9
9
  <%= parameters %>
@@ -11,7 +11,7 @@
11
11
  <td><%= parameter.in %></td>
12
12
  <td><%= parameter.schema.type %></td>
13
13
  <td><%= parameter.required? %></td>
14
- <td><%= markdown(parameter.description) %>
14
+ <td><%= parameter.description_html %>
15
15
  <% if parameter.schema.enum %>
16
16
  <p>Available items:</p>
17
17
  <ul>
@@ -9,7 +9,7 @@
9
9
  <tr>
10
10
  <td><%= key %></td>
11
11
  <td>
12
- <%= markdown(response.description) %>
12
+ <%= response.description_html %>
13
13
  <% if response.content['application/json']
14
14
  if response.content['application/json']["example"]
15
15
  request_body = json_prettyprint(response.content['application/json']["example"])
@@ -1,26 +1,26 @@
1
1
  <h3 id="<%= id = 'schema-' + title; id.parameterize %>"><%= title %></h3>
2
- <%= markdown(schema.description) %>
2
+ <%= schema.description_html %>
3
3
  <% if properties.any? %>
4
- <table>
4
+ <table class='<%= id.parameterize %>'>
5
5
  <thead>
6
6
  <tr><th>Name</th><th>Type</th><th>Required</th><th>Description</th><th>Schema</th></tr>
7
7
  </thead>
8
8
  <tbody>
9
- <% properties.each do |property| %>
9
+ <% properties.each do |property_name, property_attributes| %>
10
10
  <tr>
11
- <td><%= property[0] %></td>
12
- <td><%= property[1].type %></td>
13
- <td><%= property[1].required.present? %></td>
14
- <td><%= markdown(property[1].description) %></td>
11
+ <td><%= property_name %></td>
12
+ <td><%= property_attributes.type %></td>
13
+ <td><%= schema.requires?(property_name) %></td>
14
+ <td><%= property_attributes.description_html %></td>
15
15
  <td>
16
16
  <%=
17
- schema = property[1]
17
+ linked_schema = property_attributes
18
18
  # If property is an array, check the items property for a reference.
19
- if property[1].type == 'array'
20
- schema = property[1]['items']
19
+ if property_attributes.type == 'array'
20
+ linked_schema = property_attributes['items']
21
21
  end
22
- # Only print a link if it's a referenced object.
23
- 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/' %>
22
+ # Only print a link if it's a named schema
23
+ get_schema_link(linked_schema) if linked_schema.name %>
24
24
  </td>
25
25
  </tr>
26
26
  <% end %>
@@ -1,3 +1,3 @@
1
1
  module GovukTechDocs
2
- VERSION = "2.2.0".freeze
2
+ VERSION = "2.2.1".freeze
3
3
  end
metadata CHANGED
@@ -1,29 +1,15 @@
1
1
  --- !ruby/object:Gem::Specification
2
2
  name: govuk_tech_docs
3
3
  version: !ruby/object:Gem::Version
4
- version: 2.2.0
4
+ version: 2.2.1
5
5
  platform: ruby
6
6
  authors:
7
7
  - Government Digital Service
8
8
  autorequire:
9
9
  bindir: exe
10
10
  cert_chain: []
11
- date: 2021-03-12 00:00:00.000000000 Z
11
+ date: 2021-03-15 00:00:00.000000000 Z
12
12
  dependencies:
13
- - !ruby/object:Gem::Dependency
14
- name: activesupport
15
- requirement: !ruby/object:Gem::Requirement
16
- requirements:
17
- - - ">="
18
- - !ruby/object:Gem::Version
19
- version: '0'
20
- type: :runtime
21
- prerelease: false
22
- version_requirements: !ruby/object:Gem::Requirement
23
- requirements:
24
- - - ">="
25
- - !ruby/object:Gem::Version
26
- version: '0'
27
13
  - !ruby/object:Gem::Dependency
28
14
  name: chronic
29
15
  requirement: !ruby/object:Gem::Requirement
@@ -156,28 +142,14 @@ dependencies:
156
142
  requirements:
157
143
  - - "~>"
158
144
  - !ruby/object:Gem::Version
159
- version: 0.5.0
145
+ version: 0.9.0
160
146
  type: :runtime
161
147
  prerelease: false
162
148
  version_requirements: !ruby/object:Gem::Requirement
163
149
  requirements:
164
150
  - - "~>"
165
151
  - !ruby/object:Gem::Version
166
- version: 0.5.0
167
- - !ruby/object:Gem::Dependency
168
- name: pry
169
- requirement: !ruby/object:Gem::Requirement
170
- requirements:
171
- - - ">="
172
- - !ruby/object:Gem::Version
173
- version: '0'
174
- type: :runtime
175
- prerelease: false
176
- version_requirements: !ruby/object:Gem::Requirement
177
- requirements:
178
- - - ">="
179
- - !ruby/object:Gem::Version
180
- version: '0'
152
+ version: 0.9.0
181
153
  - !ruby/object:Gem::Dependency
182
154
  name: redcarpet
183
155
  requirement: !ruby/object:Gem::Requirement
@@ -192,48 +164,6 @@ dependencies:
192
164
  - - "~>"
193
165
  - !ruby/object:Gem::Version
194
166
  version: 3.5.0
195
- - !ruby/object:Gem::Dependency
196
- name: sass
197
- requirement: !ruby/object:Gem::Requirement
198
- requirements:
199
- - - ">="
200
- - !ruby/object:Gem::Version
201
- version: '0'
202
- type: :runtime
203
- prerelease: false
204
- version_requirements: !ruby/object:Gem::Requirement
205
- requirements:
206
- - - ">="
207
- - !ruby/object:Gem::Version
208
- version: '0'
209
- - !ruby/object:Gem::Dependency
210
- name: sprockets
211
- requirement: !ruby/object:Gem::Requirement
212
- requirements:
213
- - - "~>"
214
- - !ruby/object:Gem::Version
215
- version: 4.0.0
216
- type: :runtime
217
- prerelease: false
218
- version_requirements: !ruby/object:Gem::Requirement
219
- requirements:
220
- - - "~>"
221
- - !ruby/object:Gem::Version
222
- version: 4.0.0
223
- - !ruby/object:Gem::Dependency
224
- name: bundler
225
- requirement: !ruby/object:Gem::Requirement
226
- requirements:
227
- - - "~>"
228
- - !ruby/object:Gem::Version
229
- version: 2.2.0
230
- type: :development
231
- prerelease: false
232
- version_requirements: !ruby/object:Gem::Requirement
233
- requirements:
234
- - - "~>"
235
- - !ruby/object:Gem::Version
236
- version: 2.2.0
237
167
  - !ruby/object:Gem::Dependency
238
168
  name: byebug
239
169
  requirement: !ruby/object:Gem::Requirement