From ffa9f0280327d36db80f70ed291551d3ac805b96 Mon Sep 17 00:00:00 2001 From: Gabriel Custodio Date: Tue, 27 Aug 2019 18:42:11 -0300 Subject: [PATCH 1/8] Adds x-logo to openapi's fixture file --- spec/fixtures/open_api.yml | 4 ++++ 1 file changed, 4 insertions(+) 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 From 090b8294a6e21bbe72b00f922d32b0b5039eade0 Mon Sep 17 00:00:00 2001 From: Gabriel Custodio Date: Tue, 27 Aug 2019 18:43:05 -0300 Subject: [PATCH 2/8] Adds openapi x-logo entry to feature file --- features/open_api.feature | 14 ++++++++++++-- 1 file changed, 12 insertions(+), 2 deletions(-) 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": [ From a951b051b5afbbd9cdd4e6e76fb0b626f0c34c72 Mon Sep 17 00:00:00 2001 From: Gabriel Custodio Date: Tue, 27 Aug 2019 18:44:13 -0300 Subject: [PATCH 3/8] Adds openapi's x-logo --- example/config/open_api.yml | 4 ++++ lib/rspec_api_documentation.rb | 1 + lib/rspec_api_documentation/open_api/info.rb | 1 + lib/rspec_api_documentation/open_api/x_logo.rb | 9 +++++++++ 4 files changed, 15 insertions(+) create mode 100644 lib/rspec_api_documentation/open_api/x_logo.rb 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/lib/rspec_api_documentation.rb b/lib/rspec_api_documentation.rb index 5986aadb..a9ebba96 100644 --- a/lib/rspec_api_documentation.rb +++ b/lib/rspec_api_documentation.rb @@ -71,6 +71,7 @@ module OpenApi autoload :Schema autoload :SecurityDefinitions autoload :SecuritySchema + autoload :XLogo end module Views 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 From 219ef8304f7dab5355d2ce0bf52a23b17f7f52b4 Mon Sep 17 00:00:00 2001 From: Gabriel Rodriguez Date: Mon, 31 Aug 2020 16:09:42 -0300 Subject: [PATCH 4/8] Change markdown example explanation tag to non-escaped syntax --- templates/rspec_api_documentation/markdown_example.mustache | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) 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? }} From af1863a00c2054c7296e426dc422edf2db2d13ab Mon Sep 17 00:00:00 2001 From: Gabriel Rodriguez Date: Thu, 3 Sep 2020 11:55:58 -0300 Subject: [PATCH 5/8] Add docusaurus format --- lib/rspec_api_documentation.rb | 3 + .../views/docusaurus_example.rb | 35 ++++++ .../views/docusaurus_index.rb | 24 +++++ .../writers/docusaurus_writer.rb | 19 ++++ templates/custom/docusaurus_example.mustache | 102 ++++++++++++++++++ templates/custom/docusaurus_index.mustache | 21 ++++ 6 files changed, 204 insertions(+) create mode 100644 lib/rspec_api_documentation/views/docusaurus_example.rb create mode 100644 lib/rspec_api_documentation/views/docusaurus_index.rb create mode 100644 lib/rspec_api_documentation/writers/docusaurus_writer.rb create mode 100644 templates/custom/docusaurus_example.mustache create mode 100644 templates/custom/docusaurus_index.mustache diff --git a/lib/rspec_api_documentation.rb b/lib/rspec_api_documentation.rb index a9ebba96..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 @@ -89,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/views/docusaurus_example.rb b/lib/rspec_api_documentation/views/docusaurus_example.rb new file mode 100644 index 00000000..9dc24b71 --- /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}_#{description.downcase}" + end + + def response_format + JSON.parse(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/templates/custom/docusaurus_example.mustache b/templates/custom/docusaurus_example.mustache new file mode 100644 index 00000000..9ddeefa4 --- /dev/null +++ b/templates/custom/docusaurus_example.mustache @@ -0,0 +1,102 @@ +--- +id: {{ id }} +title: {{ resource_name }} - {{ description }} +--- + +# {{ resource_name }} API +{{# resource_explanation }} + +{{{ resource_explanation }}} +{{/ resource_explanation }} + +## {{ description }} + +### {{ 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..9f2dd655
--- /dev/null
+++ b/templates/custom/docusaurus_index.mustache
@@ -0,0 +1,21 @@
+---
+id: {{ id }}
+title: {{ api_name }} Index
+---
+
+
+# {{ api_name }}
+{{{ api_explanation }}}
+
+{{# sections }}
+## {{ resource_name }}
+{{# resource_explanation }}
+
+{{{ resource_explanation }}}
+{{/ resource_explanation }}
+
+{{# examples }}
+* [{{ description }}]({{ dirname }}/{{ filename }})
+{{/ examples }}
+
+{{/ sections }}

From 9f97cb3cdd664c5a1835a2915fc579c298a4cc43 Mon Sep 17 00:00:00 2001
From: Gabriel Rodriguez 
Date: Thu, 3 Sep 2020 16:03:22 -0300
Subject: [PATCH 6/8] Enhance docursaurus template flexibility

---
 .../views/docusaurus_example.rb                   |  4 ++--
 templates/custom/docusaurus_example.mustache      | 15 ++++++++-------
 templates/custom/docusaurus_index.mustache        |  1 -
 3 files changed, 10 insertions(+), 10 deletions(-)

diff --git a/lib/rspec_api_documentation/views/docusaurus_example.rb b/lib/rspec_api_documentation/views/docusaurus_example.rb
index 9dc24b71..9e1972b6 100644
--- a/lib/rspec_api_documentation/views/docusaurus_example.rb
+++ b/lib/rspec_api_documentation/views/docusaurus_example.rb
@@ -21,11 +21,11 @@ def extension
       end
 
       def id
-        "#{dirname}_#{description.downcase}"
+        "#{dirname}_#{sanitize(description.downcase)}"
       end
 
       def response_format
-        JSON.parse(response_body)
+        JSON.parse(requests.first[:response_body])
         'json'
       rescue JSON::ParserError
         nil
diff --git a/templates/custom/docusaurus_example.mustache b/templates/custom/docusaurus_example.mustache
index 9ddeefa4..98481463 100644
--- a/templates/custom/docusaurus_example.mustache
+++ b/templates/custom/docusaurus_example.mustache
@@ -9,7 +9,7 @@ title: {{ resource_name }} - {{ description }}
 {{{ resource_explanation }}}
 {{/ resource_explanation }}
 
-## {{ description }}
+## {{{ description }}}
 
 ### {{ http_method }} {{ route }}
 {{# explanation }}
@@ -23,7 +23,7 @@ title: {{ resource_name }} - {{ description }}
 | Name | Description | Required | Scope |
 |------|-------------|----------|-------|
 {{# parameters }}
-| {{ name }} | {{ description }} | {{ required }} | {{ scope }} |
+| {{{ name }}} | {{{ description }}} | {{{ required }}} | {{{ scope }}} |
 {{/ parameters }}
 
 {{/ has_parameters? }}
@@ -34,7 +34,7 @@ title: {{ resource_name }} - {{ description }}
 | Name | Description | Scope |
 |------|-------------|-------|
 {{# response_fields }}
-| {{ name }} | {{ description }} | {{ scope }} |
+| {{{ name }}} | {{{ description }}} | {{{ scope }}} |
 {{/ response_fields }}
 
 {{/ has_response_fields? }}
@@ -44,20 +44,20 @@ title: {{ resource_name }} - {{ description }}
 #### Headers
 
 ```
-{{ request_headers_text }}
+{{{ request_headers_text }}}
 ```
 
 #### Route
 
 ```
-{{ request_method }} {{ request_path }}
+{{ request_method }} {{{ request_path }}}
 ```
 {{# request_query_parameters_text }}
 
 #### Query Parameters
 
 ```
-{{ request_query_parameters_text }}
+{{{ request_query_parameters_text }}}
 ```
 {{/ request_query_parameters_text }}
 {{# request_body }}
@@ -72,7 +72,8 @@ title: {{ resource_name }} - {{ description }}
 
 #### cURL
 
-
{{ curl }}
+```
+{{{ curl }}}
 ```
 {{/ curl }}
 
diff --git a/templates/custom/docusaurus_index.mustache b/templates/custom/docusaurus_index.mustache
index 9f2dd655..c4d330b5 100644
--- a/templates/custom/docusaurus_index.mustache
+++ b/templates/custom/docusaurus_index.mustache
@@ -3,7 +3,6 @@ id: {{ id }}
 title: {{ api_name }} Index
 ---
 
-
 # {{ api_name }}
 {{{ api_explanation }}}
 

From c7a51f6867ab1f798d5569f90bd15ecd7e7db975 Mon Sep 17 00:00:00 2001
From: Gabriel Rodriguez 
Date: Thu, 3 Sep 2020 16:12:46 -0300
Subject: [PATCH 7/8] Change docusaurus example template

---
 templates/custom/docusaurus_example.mustache | 7 +++----
 1 file changed, 3 insertions(+), 4 deletions(-)

diff --git a/templates/custom/docusaurus_example.mustache b/templates/custom/docusaurus_example.mustache
index 98481463..63c84c68 100644
--- a/templates/custom/docusaurus_example.mustache
+++ b/templates/custom/docusaurus_example.mustache
@@ -1,16 +1,15 @@
 ---
 id: {{ id }}
-title: {{ resource_name }} - {{ description }}
+title: {{ resource_name }}
 ---
 
-# {{ resource_name }} API
+## {{{ description }}}
+
 {{# resource_explanation }}
 
 {{{ resource_explanation }}}
 {{/ resource_explanation }}
 
-## {{{ description }}}
-
 ### {{ http_method }} {{ route }}
 {{# explanation }}
 

From 5c3f57e96f92b20f181041b3f5b71ec70f879c38 Mon Sep 17 00:00:00 2001
From: Gabriel Rodriguez 
Date: Thu, 3 Sep 2020 16:25:31 -0300
Subject: [PATCH 8/8] Change docusaurus index template

---
 templates/custom/docusaurus_index.mustache | 1 -
 1 file changed, 1 deletion(-)

diff --git a/templates/custom/docusaurus_index.mustache b/templates/custom/docusaurus_index.mustache
index c4d330b5..2f8a9f4e 100644
--- a/templates/custom/docusaurus_index.mustache
+++ b/templates/custom/docusaurus_index.mustache
@@ -3,7 +3,6 @@ id: {{ id }}
 title: {{ api_name }} Index
 ---
 
-# {{ api_name }}
 {{{ api_explanation }}}
 
 {{# sections }}