Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

GTD-2: API reference improvements #48

Merged
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
33 commits
Select commit Hold shift + click to select a range
d6358f3
Moved rendering into a separate class
lewisnyman Aug 23, 2018
ae6b562
Move operations rendering into a seperate file
lewisnyman Aug 23, 2018
0a59bd0
Moved paramters rendering into a seperate file
lewisnyman Aug 23, 2018
4e27939
Moved responses rendering into a seperate file
lewisnyman Aug 23, 2018
b054506
Add support for enum type in parameters
mikebell Aug 28, 2018
e21bec7
Fix inserting schema objects with api_schema>
mikebell Aug 28, 2018
dabc682
Render schemas below an individual path
lewisnyman Aug 28, 2018
fdbdbc8
Add paragraph tags to enum parameters
lewisnyman Aug 29, 2018
d134307
Add schema link support to nested schema objects. Move functionality …
lewisnyman Aug 29, 2018
8156fa8
Also print schema links to reference within schema array properties
lewisnyman Aug 29, 2018
38b3af1
Add start of json response output
mikebell Aug 29, 2018
35b2386
Simplified the json output generation for the response body
lewisnyman Aug 29, 2018
0d7599f
Lovely pretty JSON
lewisnyman Aug 29, 2018
b601b4e
Display referenced data structures in response bodies
lewisnyman Aug 30, 2018
b315d2d
Remove extra table row and space
mikebell Aug 30, 2018
0b229ec
Support array type in responses
mikebell Aug 30, 2018
61f9b97
Prevented response bodies from breaking page layout
lewisnyman Aug 30, 2018
fd28f5f
Printed nested references to schemas, currently one level deep
lewisnyman Aug 30, 2018
b6cc92f
Recursively render schemas referenced by other schemas referenced by …
lewisnyman Aug 30, 2018
369ae2b
Start of allOf support
mikebell Aug 30, 2018
4a2804c
Merge branch 'json-response-output' of github.com:ConvivioTeam/tech-d…
mikebell Aug 30, 2018
66cb0e6
Render AllOf properties
lewisnyman Aug 30, 2018
8ccf86e
Do not print schema links of properties of referenced schema objects
lewisnyman Aug 30, 2018
31c02fd
Print schema objects referenced in arrays for single paths
lewisnyman Aug 30, 2018
aaef8d5
Add AllOf support to schemas referenced by a single printed path
lewisnyman Aug 30, 2018
b51feec
Support example responses inline
mikebell Sep 6, 2018
f593b79
Pretty print example response
mikebell Sep 6, 2018
aa920b3
Add support for markdown in response descriptions
mikebell Sep 6, 2018
ff44e27
Correctly render nested array and items, with allOf support, in respo…
lewisnyman Sep 6, 2018
5a08292
Merge branch 'json-response-output' into GTD-2-api-reference-improvem…
mikebell Sep 6, 2018
a93c41f
Fixed the rendering of schemas on a single path, the template expects…
lewisnyman Sep 6, 2018
89aa8a1
Fixed linting errors
lewisnyman Sep 6, 2018
b2ce26b
Update tests
lewisnyman Sep 7, 2018
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 3 additions & 0 deletions .rubocop.yml
Original file line number Diff line number Diff line change
Expand Up @@ -6,3 +6,6 @@ Naming/HeredocDelimiterNaming:

Lint/NestedMethodDefinition:
Enabled: false

Performance/HashEachMethods:
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Most objects constructed by openapi3_parser support .each but not .each_value but Rubocop treats it as a hash.

Copy link
Contributor

@MatMoore MatMoore Sep 7, 2018

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fair enough. Makes me wonder if we should add #each_value to the parser at some point though (cc @kevindew)

Enabled: false
27 changes: 16 additions & 11 deletions lib/assets/stylesheets/modules/_technical-documentation.scss
Original file line number Diff line number Diff line change
Expand Up @@ -3,11 +3,11 @@
@mixin heading-offset($tabletTopMargin) {
// Scale margins with font size on mobile (16/19ths)
$mobileTopMargin: ceil($tabletTopMargin * (16 / 19));

// Offset headings down on mobile so that linking to anchors they appear after
// the sticky 'table of contents' element
$stickyTocOffset: 20px + $gutter-half + 10px + 1px;

// Pad the heading so that when linking to an anchor there is at most a
// $gutter-half (mobile) or $gutter (tablet and above) sized gap between the
// top of the viewport and the heading.
Expand All @@ -25,9 +25,9 @@
display: block;
margin: 0 $gutter-half 10px;
max-width: 40em;

line-height: 1.4;

color: $text-colour;

@include media(tablet) {
Expand All @@ -45,14 +45,14 @@
@include bold-48;
@include heading-offset($gutter * 2);
border-top: 5px solid $text-colour;

&:first-of-type {
@include heading-offset($gutter);
border-top: none;
}
}

h2 {
h2 {
@include bold-36;
@include heading-offset($gutter * 1.5);
}
Expand Down Expand Up @@ -125,7 +125,7 @@

ol + p, ul + p, .table-container + p {
margin-top: ceil($gutter * (16 / 19));

@include media(tablet) {
margin-top: $gutter;
}
Expand All @@ -144,6 +144,11 @@
overflow: auto;
position: relative;
border: 1px solid $code-02;
// Restrict the width of pre tags, as they have a tendency grow larger than
// the viewport when placed within table cells.
// @todo: Use table-layout: fixed, and remove the max-width definition from
// .technical-documentation so tables can fill the viewport.
max-width: 40em;
}

pre code {
Expand All @@ -156,11 +161,11 @@
background: $code-01;
padding: 3px 5px;
border-radius: 1px;

font-family: monaco, Consolas, "Lucida Console", monospace;
font-size: 15px;
color: $code-0E;

@include media(tablet) {
font-size: 16px;
}
Expand Down Expand Up @@ -191,11 +196,11 @@
display: block;
max-width: 100%;
overflow-x: auto;

margin-top: $gutter-half;
}

table {
table {
width: 100%;

border-collapse: collapse;
Expand Down
2 changes: 1 addition & 1 deletion lib/govuk_tech_docs.rb
Original file line number Diff line number Diff line change
Expand Up @@ -20,7 +20,7 @@
require 'govuk_tech_docs/tech_docs_html_renderer'
require 'govuk_tech_docs/unique_identifier_extension'
require 'govuk_tech_docs/unique_identifier_generator'
require 'govuk_tech_docs/api_reference/api_reference'
require 'govuk_tech_docs/api_reference/api_reference_extension'

module GovukTechDocs
# Configure the tech docs template
Expand Down
173 changes: 0 additions & 173 deletions lib/govuk_tech_docs/api_reference/api_reference.rb

This file was deleted.

100 changes: 100 additions & 0 deletions lib/govuk_tech_docs/api_reference/api_reference_extension.rb
Original file line number Diff line number Diff line change
@@ -0,0 +1,100 @@
require 'erb'
require 'openapi3_parser'
require 'uri'
require 'pry'
require 'govuk_tech_docs/api_reference/api_reference_renderer'

module GovukTechDocs
module ApiReference
class Extension < Middleman::Extension
expose_to_application api: :api

def initialize(app, options_hash = {}, &block)
super

@app = app
@config = @app.config[:tech_docs]

# If no api path then just return.
if @config['api_path'].to_s.empty?
raise 'No api path defined in tech-docs.yml'
end

# Is the api_path a url or path?
if uri?(@config['api_path'])
@api_parser = true
@document = Openapi3Parser.load_url(@config['api_path'])
elsif File.exist?(@config['api_path'])
# Load api file and set existence flag.
@api_parser = true
@document = Openapi3Parser.load_file(@config['api_path'])
else
@api_parser = false
raise 'Unable to load api path from tech-docs.yml'
end
@render = Renderer.new(@app, @document)
end

def uri?(string)
uri = URI.parse(string)
%w(http https).include?(uri.scheme)
rescue URI::BadURIError
false
rescue URI::InvalidURIError
false
end

def api(text)
if @api_parser == true

keywords = {
'api&gt;' => 'default',
'api_schema&gt;' => 'schema'
}

regexp = keywords.map { |k, _| Regexp.escape(k) }.join('|')

md = text.match(/^<p>(#{regexp})/)
if md
key = md.captures[0]
type = keywords[key]

text.gsub!(/#{ Regexp.escape(key) }\s+?/, '')

# Strip paragraph tags from text
text = text.gsub(/<\/?[^>]*>/, '')
text = text.strip

if text == 'api&gt;'
@render.api_full(api_info, api_server)
elsif type == 'default'
output = @render.path(text)
# Render any schemas referenced in the above path
output += @render.schemas_from_path(text)
output
else
@render.schema(text)
end

else
return text
end
else
text
end
end

private

def api_info
@document.info
end

def api_server
@document.servers[0]
end
end
end
end

::Middleman::Extensions.register(:api_reference, GovukTechDocs::ApiReference::Extension)
Loading