apiculture 0.1.6 → 0.1.7

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: be857ef48fe8ec836d116ed89ed39c2cf55d2d60e4a25ae81eab0ccdf2b05f36
-  data.tar.gz: 737058ecf04cb0af193c24438f7c3a96c16a2551079aa13f4bcfbed2afa14fe8
+  metadata.gz: 21e9fada9f8ba88c058f19789d597059bb30b055fe92c10e27953c5df6296758
+  data.tar.gz: 7b3c02a5587b6976a2a1a7b11656834824e32887b9dde3922542687fcbe63c71
 SHA512:
-  metadata.gz: 39564495733b83ca4ce0e1963b470d9836e5ce549827f93689bebfe4f5f8e57fb368497a407142f1c6c78143ad6c56a6a5a4f74ba29bdf199704bce58d720885
-  data.tar.gz: 6c1e15fe7e3c009349d17cf59d5686b81ccc6e6c94724a89b343b404afd3c013ee8505bebe75c3228774215f7065c1faf11872589de6e6b78abafe8d462f78f7
+  metadata.gz: b0818c0fd6c04efa47f0cabcd0927c13516bd293d7486fea8750b7325d260208b3134432ebf43fbc9d7f0321a8ff7b8e5ea07e6f679e59b1df62e0f5f105f1b7
+  data.tar.gz: 853ca12aefe6005ae08432d29f902f6a1584252db87663c08c96a00f47d7b771108e2485f39e7400615e8f54243f68f6abf2e8406a963def5e3821c9ee62a6fc

data/lib/apiculture.rb

@@ -9,6 +9,7 @@ module Apiculture
   require_relative 'apiculture/markdown_segment'
   require_relative 'apiculture/timestamp_promise'
   require_relative 'apiculture/app_documentation'
+  require_relative 'apiculture/openapi_documentation'
   
   def self.extended(in_class)
     in_class.send(:include, SinatraInstanceMethods)
@@ -205,7 +206,7 @@ module Apiculture
   def api_documentation
     AppDocumentation.new(self, @apiculture_mounted_at.to_s, @apiculture_actions_and_docs || [])
   end
-  
+
   # Define an API method. Under the hood will call the related methods in Sinatra
   # to define the route.
   def api_method(http_verb, path, options={}, &blk)

data/lib/apiculture/app_documentation.rb

@@ -25,6 +25,10 @@ class Apiculture::AppDocumentation
   # Generates a Markdown string that contains the entire API documentation
   def to_markdown
     (['## %s' % @app_title] + to_markdown_slices).join("\n\n")
+  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

data/lib/apiculture/openapi_documentation.rb

@@ -0,0 +1,224 @@
+# frozen_string_literal: true
+require 'yaml'
+require 'base64'
+module OpenApiDocumentation
+  class Base
+    def initialize(app, prefix, chunks)
+      @app, @prefix = app, prefix
+      @paths = chunks.select { |chunk| chunk.respond_to?(:http_verb) }
+      @data = {
+        openapi: '3.0.0',
+        info: { 
+          title: @app.to_s, 
+          version: '0.0.1', 
+          description: @app.to_s + " " + chunks.select { |chunk| chunk.respond_to?(:to_markdown) }.map(&:to_markdown).join("\n")
+        },
+        tags: []
+      }
+      @data[:paths] = build_paths
+    end
+
+    def to_yaml
+      JSON.load(@data.to_json).to_yaml # trickery to get string based yaml
+    end
+
+    def paths
+      @data[:paths]
+    end
+
+    def spec
+      @data      
+    end
+
+    private
+
+    def build_paths
+      paths = {}
+      @paths.each do |path|
+        path = Path.new(path, @prefix, @app)
+        paths = merge_paths(paths, path)
+      end
+      paths
+    end
+
+    # We don't have deep_merge here so this is the poor man's alternative
+    def merge_paths(paths, path)
+      if paths.key?(path.name)
+        paths[path.name].merge!(path.build[path.name])
+      else
+        paths.merge!(path.build)
+      end
+      paths
+    end
+
+  end
+
+  class Path
+    VERBS_WITHOUT_BODY = %w(get head delete options)
+
+    def initialize(path, prefix, app)
+      @path, @prefix, @app = path, prefix, app
+    end
+
+    def build
+      request_body = build_request_body unless VERBS_WITHOUT_BODY.include?(@path.http_verb)
+      {
+        name =>
+        {
+          @path.http_verb.to_sym => {
+            summary: @path.description,
+            description: @path.description,
+            tags: [ @app.to_s ],
+            parameters: build_parameters,
+            requestBody: request_body,
+            responses: build_responses,
+            operationId: operation_id
+          }.delete_if { |_k, v| v.nil? || v.empty? }
+        }
+      }
+    end
+
+    def name
+      full_path = @path.path.to_s
+      @path.route_parameters.each do |parameter|
+        # This is a bit confusing but naming is a little different between
+        # apiculture and openapi
+        full_path.gsub!(":#{parameter.name}", "\{#{parameter.name}\}")
+      end
+      Util.clean_path("#{@prefix}#{full_path}")
+    end
+
+    private
+
+    def operation_id
+      # base64 encoding to make sure these ids are safe to use in an url
+      Base64.urlsafe_encode64("#{@path.http_verb}#{@prefix}#{@path.path}")
+    end
+
+    def build_parameters
+      if VERBS_WITHOUT_BODY.include?(@path.http_verb)
+        build_route_parameters + build_query_parameters
+      else
+        build_route_parameters
+      end
+    end
+
+    def build_route_parameters
+      route_params = @path.route_parameters.map do |parameter|
+        {
+          name: parameter.name,
+          description: parameter.description,
+          required: true,
+          in: :path,
+          schema: {
+            type: Util.map_type(parameter.matchable),
+            example: Util.map_example(parameter.matchable)
+          }
+        }
+      end
+      route_params
+    end
+
+    def build_query_parameters
+      params = @path.parameters.map do |parameter|
+        {
+          name: parameter.name,
+          description: parameter.description,
+          required: true,
+          in: :query,
+          schema: {
+            type: Util.map_type(parameter.matchable),
+            example: parameter.matchable
+          }
+        }
+      end
+      params
+    end
+
+    def build_request_body
+      return nil if VERBS_WITHOUT_BODY.include?(@path.http_verb)
+      
+      body_params = Hash[ @path.parameters.collect do |parameter|
+        [parameter.name, {
+          type: Util.map_type(parameter.matchable),
+          description: parameter.description
+        }]
+      end ]
+
+      return nil if body_params.count == 0
+
+      schema = {
+        type: :object,
+        properties: body_params
+      }
+
+      schema[:required] = @path.parameters.select(&:required).map(&:name) if @path.parameters.select(&:required).map(&:name).count > 0
+      {
+        content: {
+          "application/json": {
+            schema: schema
+          }
+        }
+      }
+    end
+
+    def build_responses
+      responses = Hash[@path.responses.collect do |response|
+        _response = {
+          description: response.description
+        }
+
+        unless response.jsonable_object_example.nil? || response.jsonable_object_example.empty?
+          _response[:content] = {
+            'application/json': {
+                schema: 
+                  { type: 'object',
+                  properties: Util.response_to_schema(response.jsonable_object_example) }
+            }
+          }
+        end
+
+        [response.http_status_code.to_s, _response]
+      end ]
+      responses
+    end
+  end
+
+  class Util
+    TYPES = {
+      String => 'string',
+      Integer => 'integer',
+      TrueClass => 'boolean'
+    }.freeze
+
+    EXAMPLES = {
+      String => 'string',
+      Integer => 1234,
+      TrueClass => true
+    }.freeze
+
+    def self.response_to_schema(response)
+      schema = {}
+      return nil if response.nil? || response.empty? || response.class == String
+      response.each do |key, value|
+        schema[key] = {
+          type: 'string',
+          example: value.to_s
+        }
+      end
+      schema
+    end
+
+    def self.map_type(type)
+      TYPES.fetch(type, 'string')
+    end
+
+    def self.map_example(type)
+      EXAMPLES.fetch(type, 'string')
+    end
+
+    def self.clean_path(path)
+      path.gsub(/\/\?\*\?$/, '')
+    end
+  end
+end

data/lib/apiculture/version.rb

@@ -1,3 +1,3 @@
 module Apiculture
-  VERSION = '0.1.6'
+  VERSION = '0.1.7'
 end

data/spec/apiculture/openapi_documentation_spec.rb

@@ -0,0 +1,197 @@
+require_relative '../spec_helper'
+
+describe 'Apiculture.api_documentation' do
+  let!(:test_class) do
+    class PancakeApi < Apiculture::App
+      extend Apiculture
+
+      documentation_build_time!
+
+      desc 'Order a pancake'
+      required_param :diameter, 'Diameter of the pancake. The pancake will be **bold**', Integer
+      param :topping, 'Type of topping', String
+      pancake_response_info = <<~EOS
+        When the pancake has been baked successfully
+        The pancake will have the following properties:
+
+        * It is going to be round
+        * It is going to be delicious
+      EOS
+      responds_with 200, pancake_response_info, { id: 'abdef..c21' }
+      api_method :post, '/pancakes' do
+      end
+
+      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
+
+  let(:documentation) { PancakeApi.api_documentation }
+  let(:open_api_map) { documentation.to_openapi.spec }
+
+  describe '.to_openapi' do
+    it 'will have openapi version' do
+      expect(open_api_map).to include(openapi: '3.0.0')
+    end
+
+    describe 'info' do
+      let(:info) { open_api_map.fetch(:info) }
+
+      it 'will not to be empty' do
+        expect(info).not_to be_empty
+      end
+
+      it 'will have title' do
+        expect(info).to include(title: 'PancakeApi')
+      end
+
+      it 'will have version' do
+        expect(info).to include(version: '0.0.1')
+      end
+
+      it 'will have description' do
+        expect(info).to include(:description)
+        expect(info[:description]).to include('PancakeApi Documentation built on')
+      end
+    end
+
+    describe 'paths' do
+      let(:paths) { open_api_map.fetch(:paths) }
+
+      it 'will have paths' do
+        expect(paths).not_to be_empty
+      end
+
+      it 'will have 4 paths' do
+        expect(paths.size).to eq(3)
+      end
+
+      context 'POST /pancakes' do
+        let(:post_pancakes) { paths.dig('/pancakes', :post) }
+
+        it 'will have route' do
+          expect(post_pancakes).not_to be_empty
+        end
+
+        describe 'request body content' do
+          let(:request_content) { post_pancakes.dig(:requestBody, :content) }
+          it 'will have correct JSON content type' do
+            expect(request_content).to have_key(:'application/json')
+          end
+
+          describe 'schema' do
+            let(:schema) { request_content.dig(:'application/json', :schema) }
+            it 'will have type' do
+              expect(schema).to include(type: :object)
+            end
+
+            it 'will have required parameters' do
+              expect(schema).to include(required: [:diameter])
+            end
+
+            describe 'properties' do
+              let(:properties) { schema.fetch(:properties) }
+              it 'will have all properties' do
+                expect(properties).to have_key :diameter
+                expect(properties).to have_key :topping
+              end
+            end
+          end
+        end
+      end
+
+      context 'GET /pancake/:id' do
+        let(:get_pancake_by_id_path) { paths.dig('/pancake/{id}', :get) }
+        it 'will have route' do
+          expect(get_pancake_by_id_path).not_to be_empty
+        end
+
+        it 'will have summary' do
+          expect(get_pancake_by_id_path).to include(summary: 'Check the pancake status')
+        end
+
+        it 'will have a description' do
+          expect(get_pancake_by_id_path).to include(description: 'Check the pancake status')
+        end
+
+        it 'will have operationId' do
+          expect(get_pancake_by_id_path).to have_key :operationId
+        end
+
+        describe 'parameters' do
+          let(:parameter) { get_pancake_by_id_path.fetch(:parameters).first }
+
+          it 'will contain parameter' do
+            expect(parameter).not_to be_empty
+          end
+
+          it 'will have required propertie' do
+            expect(parameter).to include(required: true)
+          end
+
+          it 'will indicate a path parameter' do
+            expect(parameter).to include(in: :path)
+          end
+
+          describe 'schema' do
+            let(:schema) { parameter.fetch(:schema) }
+            it 'will have object type' do
+              expect(schema).to include(type: 'string')
+            end
+
+            it 'will have an example' do
+              expect(schema).to include(example: 'string')
+            end
+          end
+        end
+
+        describe 'responses' do
+          let(:responses) { get_pancake_by_id_path.fetch(:responses) }
+
+          it 'will contain all responses by response code' do
+            expect(responses).to have_key('200')
+            expect(responses).to have_key('404')
+          end
+
+          describe 'response 200' do
+            let(:response_200) { responses.fetch('200') }
+
+            it 'will have description' do
+              expect(response_200).to include(description: 'When the pancake is found')
+            end
+
+            it 'will have correct content type' do
+              expect(response_200.fetch(:content)).to have_key(:'application/json')
+            end
+
+            describe 'schema' do
+              let(:schema) { response_200.dig(:content, :'application/json', :schema) }
+              
+              it 'will have object type' do
+                expect(schema).to include(type: 'object')
+              end
+
+              it 'will have properties' do
+                expect(schema).to have_key :properties
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

metadata

@@ -1,15 +1,15 @@
 --- !ruby/object:Gem::Specification
 name: apiculture
 version: !ruby/object:Gem::Version
-  version: 0.1.6
+  version: 0.1.7
 platform: ruby
 authors:
 - Julik Tarkhanov
 - WeTransfer
-autorequire: 
+autorequire:
 bindir: bin
 cert_chain: []
-date: 2021-01-27 00:00:00.000000000 Z
+date: 2021-06-28 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: mustermann
@@ -191,12 +191,14 @@ files:
 - lib/apiculture/indifferent_hash.rb
 - lib/apiculture/markdown_segment.rb
 - lib/apiculture/method_documentation.rb
+- lib/apiculture/openapi_documentation.rb
 - lib/apiculture/sinatra_instance_methods.rb
 - lib/apiculture/timestamp_promise.rb
 - lib/apiculture/version.rb
 - spec/apiculture/action_spec.rb
 - spec/apiculture/app_documentation_spec.rb
 - spec/apiculture/method_documentation_spec.rb
+- spec/apiculture/openapi_documentation_spec.rb
 - spec/apiculture_spec.rb
 - spec/spec_helper.rb
 homepage: https://github.com/WeTransfer/apiculture
@@ -204,7 +206,7 @@ licenses:
 - MIT
 metadata:
   allowed_push_host: https://rubygems.org
-post_install_message: 
+post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -219,8 +221,8 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.0.3
-signing_key: 
+rubygems_version: 3.0.9
+signing_key:
 specification_version: 4
 summary: Sweet API sauce on top of Rack
 test_files: []