diff --git a/example/config/open_api.yml b/example/config/open_api.yml index 0be381d2..adb749d4 100644 --- a/example/config/open_api.yml +++ b/example/config/open_api.yml @@ -11,6 +11,10 @@ info: name: Apache 2.0 url: 'http://www.apache.org/licenses/LICENSE-2.0.html' version: 1.0.1 + x-logo: + url: "https://redocly.github.io/redoc/petstore-logo.png" + backgroundColor: "#FFFFFF" + altText: "Petstore logo" host: 'localhost:3000' schemes: - http diff --git a/features/open_api.feature b/features/open_api.feature index a24b7094..8841a8f6 100644 --- a/features/open_api.feature +++ b/features/open_api.feature @@ -73,7 +73,12 @@ Feature: Generate Open API Specification from test examples "name": "Apache 2.0", "url": "http://www.apache.org/licenses/LICENSE-2.0.html" }, - "version": "1.0.1" + "version": "1.0.1", + "x-logo": { + "url": "https://redocly.github.io/redoc/petstore-logo.png", + "backgroundColor": "#FFFFFF", + "altText": "Petstore logo" + } }, "host": "localhost:3000", "schemes": [ @@ -307,7 +312,12 @@ Feature: Generate Open API Specification from test examples "name": "Apache 2.0", "url": "http://www.apache.org/licenses/LICENSE-2.0.html" }, - "version": "1.0.1" + "version": "1.0.1", + "x-logo": { + "url": "https://redocly.github.io/redoc/petstore-logo.png", + "backgroundColor": "#FFFFFF", + "altText": "Petstore logo" + } }, "host": "localhost:3000", "schemes": [ diff --git a/lib/rspec_api_documentation.rb b/lib/rspec_api_documentation.rb index 5986aadb..32054b8e 100644 --- a/lib/rspec_api_documentation.rb +++ b/lib/rspec_api_documentation.rb @@ -47,6 +47,7 @@ module Writers autoload :SlateWriter autoload :ApiBlueprintWriter autoload :OpenApiWriter + autoload :DocusaurusWriter end module OpenApi @@ -71,6 +72,7 @@ module OpenApi autoload :Schema autoload :SecurityDefinitions autoload :SecuritySchema + autoload :XLogo end module Views @@ -88,6 +90,8 @@ module Views autoload :SlateExample autoload :ApiBlueprintIndex autoload :ApiBlueprintExample + autoload :DocusaurusExample + autoload :DocusaurusIndex end def self.configuration diff --git a/lib/rspec_api_documentation/open_api/info.rb b/lib/rspec_api_documentation/open_api/info.rb index 4c295d65..102ace5e 100644 --- a/lib/rspec_api_documentation/open_api/info.rb +++ b/lib/rspec_api_documentation/open_api/info.rb @@ -7,6 +7,7 @@ class Info < Node add_setting :contact, :schema => Contact add_setting :license, :schema => License add_setting :version, :default => '1.0.0', :required => true + add_setting :'x-logo', :schema => XLogo end end end diff --git a/lib/rspec_api_documentation/open_api/x_logo.rb b/lib/rspec_api_documentation/open_api/x_logo.rb new file mode 100644 index 00000000..1c2a1d22 --- /dev/null +++ b/lib/rspec_api_documentation/open_api/x_logo.rb @@ -0,0 +1,9 @@ +module RspecApiDocumentation + module OpenApi + class XLogo < Node + add_setting :url + add_setting :backgroundColor + add_setting :altText + end + end +end diff --git a/lib/rspec_api_documentation/views/docusaurus_example.rb b/lib/rspec_api_documentation/views/docusaurus_example.rb new file mode 100644 index 00000000..9e1972b6 --- /dev/null +++ b/lib/rspec_api_documentation/views/docusaurus_example.rb @@ -0,0 +1,35 @@ +module RspecApiDocumentation + module Views + class DocusaurusExample < MarkupExample + EXTENSION = 'md' + + def initialize(example, configuration) + super + self.template_name = 'custom/docusaurus_example' + end + + def parameters + super.map do |parameter| + parameter.merge({ + :required => parameter[:required] ? 'true' : 'false', + }) + end + end + + def extension + EXTENSION + end + + def id + "#{dirname}_#{sanitize(description.downcase)}" + end + + def response_format + JSON.parse(requests.first[:response_body]) + 'json' + rescue JSON::ParserError + nil + end + end + end +end diff --git a/lib/rspec_api_documentation/views/docusaurus_index.rb b/lib/rspec_api_documentation/views/docusaurus_index.rb new file mode 100644 index 00000000..b253b34d --- /dev/null +++ b/lib/rspec_api_documentation/views/docusaurus_index.rb @@ -0,0 +1,24 @@ +module RspecApiDocumentation + module Views + class DocusaurusIndex < MarkupIndex + SPECIAL_CHARS = /[<>:"\/\\|?*]/.freeze + + def initialize(index, configuration) + super + self.template_name = 'custom/docusaurus_index' + end + + def examples + @index.examples.map { |example| DocusaurusExample.new(example, @configuration) } + end + + def id + sanitize(api_name.to_s).downcase.underscore + end + + def sanitize(name) + name.gsub(/\s+/, '_').gsub(SPECIAL_CHARS, '') + end + end + end +end diff --git a/lib/rspec_api_documentation/writers/docusaurus_writer.rb b/lib/rspec_api_documentation/writers/docusaurus_writer.rb new file mode 100644 index 00000000..9fd00ae0 --- /dev/null +++ b/lib/rspec_api_documentation/writers/docusaurus_writer.rb @@ -0,0 +1,19 @@ +module RspecApiDocumentation + module Writers + class DocusaurusWriter < GeneralMarkupWriter + EXTENSION = 'md' + + def markup_index_class + RspecApiDocumentation::Views::DocusaurusIndex + end + + def markup_example_class + RspecApiDocumentation::Views::DocusaurusExample + end + + def extension + EXTENSION + end + end + end +end diff --git a/spec/fixtures/open_api.yml b/spec/fixtures/open_api.yml index 6ba6ab9d..3fa33759 100644 --- a/spec/fixtures/open_api.yml +++ b/spec/fixtures/open_api.yml @@ -11,6 +11,10 @@ info: name: Apache 2.0 url: 'http://www.apache.org/licenses/LICENSE-2.0.html' version: 1.0.1 + x-logo: + url: "https://redocly.github.io/redoc/petstore-logo.png" + backgroundColor: "#FFFFFF" + altText: "Petstore logo" host: 'localhost:3000' schemes: - http diff --git a/templates/custom/docusaurus_example.mustache b/templates/custom/docusaurus_example.mustache new file mode 100644 index 00000000..63c84c68 --- /dev/null +++ b/templates/custom/docusaurus_example.mustache @@ -0,0 +1,102 @@ +--- +id: {{ id }} +title: {{ resource_name }} +--- + +## {{{ description }}} + +{{# resource_explanation }} + +{{{ resource_explanation }}} +{{/ resource_explanation }} + +### {{ http_method }} {{ route }} +{{# explanation }} + +{{{ explanation }}} +{{/ explanation }} +{{# has_parameters? }} + +### Parameters + +| Name | Description | Required | Scope | +|------|-------------|----------|-------| +{{# parameters }} +| {{{ name }}} | {{{ description }}} | {{{ required }}} | {{{ scope }}} | +{{/ parameters }} + +{{/ has_parameters? }} +{{# has_response_fields? }} + +### Response Fields + +| Name | Description | Scope | +|------|-------------|-------| +{{# response_fields }} +| {{{ name }}} | {{{ description }}} | {{{ scope }}} | +{{/ response_fields }} + +{{/ has_response_fields? }} +{{# requests }} +### Request + +#### Headers + +``` +{{{ request_headers_text }}} +``` + +#### Route + +``` +{{ request_method }} {{{ request_path }}} +``` +{{# request_query_parameters_text }} + +#### Query Parameters + +``` +{{{ request_query_parameters_text }}} +``` +{{/ request_query_parameters_text }} +{{# request_body }} + +#### Body + +``` +{{{ request_body }}} +``` +{{/ request_body }} +{{# curl }} + +#### cURL + +``` +{{{ curl }}} +``` +{{/ curl }} + +{{# response_status }} +### Response + +#### Headers + +``` +{{ response_headers_text }} +``` + +#### Status + +``` +{{ response_status }} {{ response_status_text}} +``` + +{{# response_body }} +#### Body + +```{{ response_format }} +{{{ response_body }}} +``` +{{/ response_body }} +{{/ response_status }} +{{/ requests }} diff --git a/templates/custom/docusaurus_index.mustache b/templates/custom/docusaurus_index.mustache new file mode 100644 index 00000000..2f8a9f4e --- /dev/null +++ b/templates/custom/docusaurus_index.mustache @@ -0,0 +1,19 @@ +--- +id: {{ id }} +title: {{ api_name }} Index +--- + +{{{ api_explanation }}} + +{{# sections }} +## {{ resource_name }} +{{# resource_explanation }} + +{{{ resource_explanation }}} +{{/ resource_explanation }} + +{{# examples }} +* [{{ description }}]({{ dirname }}/{{ filename }}) +{{/ examples }} + +{{/ sections }} diff --git a/templates/rspec_api_documentation/markdown_example.mustache b/templates/rspec_api_documentation/markdown_example.mustache index b539b32e..95451663 100644 --- a/templates/rspec_api_documentation/markdown_example.mustache +++ b/templates/rspec_api_documentation/markdown_example.mustache @@ -9,7 +9,7 @@ ### {{ http_method }} {{ route }} {{# explanation }} -{{ explanation }} +{{{ explanation }}} {{/ explanation }} {{# has_parameters? }}