From 4aa9d1ab5e553867bcfc05bab4596f093d7abbc8 Mon Sep 17 00:00:00 2001 From: Gerard Date: Fri, 28 Jun 2024 11:46:58 +0200 Subject: [PATCH 1/4] Fix a typo --- lib/apiculture/app.rb | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/lib/apiculture/app.rb b/lib/apiculture/app.rb index 24231c4..7612df2 100644 --- a/lib/apiculture/app.rb +++ b/lib/apiculture/app.rb @@ -3,7 +3,7 @@ class Apiculture::App class << self - def use(middlreware_factory, middleware_options, &middleware_blk) + def use(middleware_factory, middleware_options, &middleware_blk) @middleware_configurations ||= [] @middleware_configurations << [middleware_factory, middleware_options, middleware_blk] end From e51b7a57e4eebec05103e270ff70f6b7b3e8ea28 Mon Sep 17 00:00:00 2001 From: Gerard Date: Fri, 28 Jun 2024 11:49:54 +0200 Subject: [PATCH 2/4] Move app.rb to the spec/support folder --- lib/apiculture.rb | 1 - {lib/apiculture => spec/support}/app.rb | 0 2 files changed, 1 deletion(-) rename {lib/apiculture => spec/support}/app.rb (100%) diff --git a/lib/apiculture.rb b/lib/apiculture.rb index b54c314..b5e88fd 100644 --- a/lib/apiculture.rb +++ b/lib/apiculture.rb @@ -2,7 +2,6 @@ module Apiculture require_relative 'apiculture/version' require_relative 'apiculture/indifferent_hash' - require_relative 'apiculture/app' require_relative 'apiculture/action' require_relative 'apiculture/sinatra_instance_methods' require_relative 'apiculture/action_definition' diff --git a/lib/apiculture/app.rb b/spec/support/app.rb similarity index 100% rename from lib/apiculture/app.rb rename to spec/support/app.rb From 07546e7e4985beee74e75c991919a9c264e87957 Mon Sep 17 00:00:00 2001 From: Gerard Date: Fri, 28 Jun 2024 12:33:35 +0200 Subject: [PATCH 3/4] Disable the docs on prod --- lib/apiculture.rb | 17 ++++++- lib/apiculture/app_documentation.rb | 16 +++---- .../apiculture/app_documentation_prod_spec.rb | 47 +++++++++++++++++++ spec/support/app.rb | 5 ++ 4 files changed, 76 insertions(+), 9 deletions(-) create mode 100644 spec/apiculture/app_documentation_prod_spec.rb diff --git a/lib/apiculture.rb b/lib/apiculture.rb index b5e88fd..bf4647d 100644 --- a/lib/apiculture.rb +++ b/lib/apiculture.rb @@ -15,6 +15,12 @@ def self.extended(in_class) super end + class Void + def <<(_item); end + def map; []; end + def select; []; end + end + IDENTITY_PROC = ->(arg) { arg } AC_APPLY_TYPECAST_PROC = ->(cast_proc_or_method, v) { @@ -276,7 +282,16 @@ def api_method(http_verb, path, options={}, &blk) end def apiculture_stack - @apiculture_actions_and_docs ||= [] + if environment == "development" + @apiculture_actions_and_docs ||= [] + else + @apiculture_actions_and_docs ||= Void.new + end @apiculture_actions_and_docs end + + # Based on the RACK_ENV it will generate documentation or not + def environment + @environment ||= ENV.fetch("RACK_ENV", "development") + end end diff --git a/lib/apiculture/app_documentation.rb b/lib/apiculture/app_documentation.rb index 5f319e2..5bba196 100644 --- a/lib/apiculture/app_documentation.rb +++ b/lib/apiculture/app_documentation.rb @@ -6,38 +6,38 @@ class TaggedMarkdown < Struct.new(:string, :section_class) def to_markdown string.to_markdown.to_s rescue string.to_s end - + def to_html '
%s
' % [Rack::Utils.escape_html(section_class), render_markdown(to_markdown)] end - + def render_markdown(s) GitHub::Markup.render('section.markdown', s.to_s) end end - + def initialize(app, mountpoint, action_definitions_and_markdown_segments) @app_title = app.to_s @mountpoint = mountpoint @chunks = action_definitions_and_markdown_segments end - + # Generates a Markdown string that contains the entire API documentation def to_markdown (['## %s' % @app_title] + to_markdown_slices).join("\n\n") - end + end def to_openapi OpenApiDocumentation::Base.new(@app_title, @mountpoint, @chunks) end - + # Generates an HTML fragment string that can be included into another HTML document def to_html_fragment to_markdown_slices.map do |tagged_markdown| tagged_markdown.to_html end.join("\n\n") end - + def to_markdown_slices markdown_slices = @chunks.map do | action_def_or_doc | if action_def_or_doc.respond_to?(:http_verb) # ActionDefinition @@ -48,7 +48,7 @@ def to_markdown_slices end end end - + # Generates a complete HTML document string that can be saved into a file def to_html require 'mustache' diff --git a/spec/apiculture/app_documentation_prod_spec.rb b/spec/apiculture/app_documentation_prod_spec.rb new file mode 100644 index 0000000..6cc3b53 --- /dev/null +++ b/spec/apiculture/app_documentation_prod_spec.rb @@ -0,0 +1,47 @@ +require_relative '../spec_helper' + +describe "Apiculture.api_documentation in prod environments" do + let(:app) do + Class.new(Apiculture::App) do + extend Apiculture + + set_environment "production" + + markdown_string 'This API is very important. Because it has to do with pancakes.' + + documentation_build_time! + + desc 'Check the pancake status' + route_param :id, 'Pancake ID to check status on' + responds_with 200, 'When the pancake is found', { status: 'Baking' } + responds_with 404, 'When no such pancake exists', { status: 'No such pancake' } + api_method :get, '/pancake/:id' do + end + + desc 'Throw away the pancake' + route_param :id, 'Pancake ID to delete' + api_method :delete, '/pancake/:id' do + end + + desc 'Pancake ingredients are in the URL' + route_param :topping_id, 'Pancake topping ID', Integer, cast: :to_i + api_method :get, '/pancake/with/:topping_id' do |topping_id| + end + end + end + + it 'does not generate any html in non-dev environments' do + docco = app.api_documentation + generated_html = docco.to_html_fragment + + expect(generated_html).to eq("") + end + + # It still generates some small bits of Markdown but not a lot + it 'does not generate app documentation in Markdown' do + docco = app.api_documentation + generated_markdown = docco.to_markdown + + expect(generated_markdown.length).to eq(30) + end +end diff --git a/spec/support/app.rb b/spec/support/app.rb index 7612df2..c6ed9c8 100644 --- a/spec/support/app.rb +++ b/spec/support/app.rb @@ -12,6 +12,11 @@ def middleware_configurations @middleware_configurations || [] end + # For testing only + def set_environment(env) + @environment ||= env + end + def get(url, **options, &handler_blk) define_action :get, url, **options, &handler_blk end From 75466f5cb6901400b3c47a67990179deb70c0cbd Mon Sep 17 00:00:00 2001 From: Gerard Date: Fri, 28 Jun 2024 12:35:05 +0200 Subject: [PATCH 4/4] Bump version --- lib/apiculture/version.rb | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/lib/apiculture/version.rb b/lib/apiculture/version.rb index 315581b..32df97b 100644 --- a/lib/apiculture/version.rb +++ b/lib/apiculture/version.rb @@ -1,3 +1,3 @@ module Apiculture - VERSION = '0.2.1'.freeze + VERSION = '0.2.2'.freeze end