API reference generated from Open API spec file

docs/configuration.md

@@ -148,3 +148,11 @@ default: `true`
 ```yaml
 show_govuk_logo: true
 ```
+
+## `api_path`
+
+Define a path to an Open API V3 spec file. This can be a relative file path or a URI to a raw file.
+
+```yaml
+api_path: ./source/pets.yml
+```

example/config/tech-docs.yml

@@ -41,3 +41,5 @@ github_repo: alphagov/example-repo
 
 redirects:
   /something/old.html: /index.html
+
+api_path: source/pets.yml

example/source/api-path.html.md

@@ -0,0 +1,7 @@
+---
+title: API /Pets
+---
+
+# API /Pets
+
+api> /pets

example/source/api-reference.html.md

@@ -0,0 +1,5 @@
+---
+title: Example API Petstore
+---
+
+api>

example/source/pets.yml

@@ -0,0 +1,106 @@
+openapi: "3.0.0"
+info:
+  version: 1.0.0
+  title: Swagger Petstore
+  description: A sample API that uses a petstore as an example to demonstrate features in the OpenAPI 3.0 specification
+  license:
+    name: MIT
+servers:
+  - url: http://petstore.swagger.io/v1
+paths:
+  /pets:
+    get:
+      summary: List all pets
+      operationId: listPets
+      tags:
+        - pets
+      parameters:
+        - name: limit
+          in: query
+          description: How many items to return at one time (max 100)
+          required: false
+          schema:
+            type: integer
+            format: int32
+      responses:
+        '200':
+          description: A paged array of pets
+          headers:
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Pets"
+        default:
+          description: unexpected error
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Error"
+    post:
+      summary: Create a pet
+      operationId: createPets
+      tags:
+        - pets
+      responses:
+        '201':
+          description: Null response
+        default:
+          description: unexpected error
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Error"
+  /pets/{petId}:
+    get:
+      summary: Info for a specific pet
+      operationId: showPetById
+      tags:
+        - pets
+      parameters:
+        - name: petId
+          in: path
+          required: true
+          description: The id of the pet to retrieve
+          schema:
+            type: string
+      responses:
+        '200':
+          description: Expected response to a valid request
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Pets"
+        default:
+          description: unexpected error
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Error"
+components:
+  schemas:
+    Pet:
+      required:
+        - id
+        - name
+      properties:
+        id:
+          type: integer
+          format: int64
+        name:
+          type: string
+        tag:
+          type: string
+    Pets:
+      type: array
+      items:
+        $ref: "#/components/schemas/Pet"
+    Error:
+      required:
+        - code
+        - message
+      properties:
+        code:
+          type: integer
+          format: int32
+        message:
+          type: string

govuk_tech_docs.gemspec

@@ -32,6 +32,8 @@ Gem::Specification.new do |spec|
   spec.add_dependency "middleman-search"
   spec.add_dependency "nokogiri"
   spec.add_dependency "redcarpet", "~> 3.3.2"
+  spec.add_dependency "openapi3_parser"
+  spec.add_dependency "pry"
 
 
   spec.add_development_dependency "bundler", "~> 1.15"

lib/govuk_tech_docs.rb

@@ -20,6 +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'
 
 module GovukTechDocs
   # Configure the tech docs template
@@ -37,7 +38,9 @@ def self.configure(context, options = {})
     context.set :markdown_engine, :redcarpet
     context.set :markdown,
         renderer: TechDocsHTMLRenderer.new(
-          with_toc_data: true
+          with_toc_data: true,
+          api: true,
+          context: context
         ),
         fenced_code_blocks: true,
         tables: true,
@@ -56,6 +59,8 @@ def self.configure(context, options = {})
     context.config[:tech_docs] = YAML.load_file('config/tech-docs.yml').with_indifferent_access
     context.activate :unique_identifier
 
+    context.activate :api_reference
+
     context.helpers do
       include GovukTechDocs::TableOfContents::Helpers
       include GovukTechDocs::ContributionBanner

lib/govuk_tech_docs/api_reference/api_reference.rb

@@ -0,0 +1,173 @@
+require 'erb'
+require 'openapi3_parser'
+require 'uri'
+require 'pry'
+
+module GovukTechDocs
+  class ApiReference < 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?
+        # @TODO Throw a middleman error?
+        return
+      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
+        # @TODO Throw a middleman error?
+        @api_parser = false
+      end
+
+      # Load template files
+      @render_api_full = get_renderer('api_reference_full.html.erb')
+      @render_path = get_renderer('path.html.erb')
+      @render_schema = get_renderer('schema.html.erb')
+    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
+
+        map = {
+          'api&gt;' => 'default',
+          'api_schema&gt;' => 'schema'
+        }
+
+        regexp = map.map { |k, _| Regexp.escape(k) }.join('|')
+
+        md = text.match(/^<p>(#{regexp})/)
+        if md
+          key = md.captures[0]
+          type = map[key]
+
+          text.gsub!(/#{ Regexp.escape(key) }\s+?/, '')
+
+          # Strip paragraph tags from text
+          text = text.gsub(/<\/?[^>]*>/, '')
+          text = text.strip
+
+          if type == 'default'
+            api_path_render(text)
+          else
+            api_schema_render(text)
+          end
+
+        else
+          return text
+        end
+      else
+        text
+      end
+    end
+
+    def api_path_render(text)
+      if text == 'api&gt;'
+        return api_full
+      else
+        # Call api parser on text
+        path = @document.paths[text]
+        output = @render_path.result(binding)
+        return output
+      end
+    end
+
+    def api_schema_render(text)
+      schemas = ''
+      schemas_data = @document.components.schemas
+      schemas_data.each do |schema_data|
+        if schema_data[0] == text
+          print schema_data[0]
+          print schema_data[1]
+        end
+      end
+      return text
+    end
+
+    def api_full
+      info = api_info
+      server = api_server
+
+      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]
+        path = path_data[1]
+        paths += @render_path.result(binding)
+      end
+      schemas = ''
+      schemas_data = @document.components.schemas
+      schemas_data.each do |schema_data|
+        title = schema_data[0]
+        schema = schema_data[1]
+        schemas += @render_schema.result(binding)
+      end
+      @render_api_full.result(binding)
+    end
+
+    def render_markdown(text)
+      if text
+        Tilt['markdown'].new(context: @app) { text }.render
+      end
+    end
+
+  private
+
+    def get_renderer(file)
+      template_path = File.join(File.dirname(__FILE__), 'templates/' + file)
+      template = File.open(template_path, 'r').read
+      ERB.new(template)
+    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 api_info
+      @document.info
+    end
+
+    def api_server
+      @document.servers[0]
+    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\//, '')
+    end
+  end
+end
+
+::Middleman::Extensions.register(:api_reference, GovukTechDocs::ApiReference)

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

@@ -0,0 +1,9 @@
+<h1 id="<%=  info.title.parameterize %>"><%= info.title %> v<%= info.version %></h1>
+<%= render_markdown(info.description) %>
+<% if server %>
+<h2 id="base-url">Base URL</h2>
+<p><strong><%= server.url %></strong></p>
+<% end %>
+<%= paths %>
+<h2 id="schemas">Schemas</h2>
+<%= schemas %>