apress-documentation 0.4.0

data/lib/apress/documentation/storage/swagger_document.rb

@@ -0,0 +1,62 @@
+require_relative 'base_storage'
+require_relative '../dsl/swagger_document'
+
+module Apress
+  module Documentation
+    module Storage
+      # Protected
+      #
+      # Описывает дополнительные данные для swagger_path в SwaggerUI
+      #
+      # Алгоритм добавления данных в SwaggerUI:
+      #  - записывакем нужные экземпляры этого класса в объекте Document(метод swagger_documents)
+      #  - сериализуем данные из swagger_documents во вьюхе в js-переменную (метод as_json в BaseStorage)
+      #  - вешаем событие на добавление данных из новосозданной переменной в HTML-таг с id == bind_id
+      #  - после отрисовки SwaggerUI, вызываем триггер события, которое добавляет дополнительные данные
+      class SwaggerDocument < BaseStorage
+        include Apress::Documentation::Dsl::SwaggerDocument
+        # Public: Ссылка на документ(Document) в котором записан данный SwaggerDocument
+        attr_reader :document
+        # Public: tag и openperation_id для SwaggerUI
+        attr_reader :tag, :operation_id
+        alias_method :title, :operation_id
+        # Public: Бизнесс описание - заполняется менаджером
+        json_attr :business_desc
+        # Public: Наличие тестов, ссылка на задачу с тестами
+        json_attr :tests
+        # Public: Публичность описываемого функционала - (Закрытый, Защищенный, Публичный)
+        json_attr :publicity
+
+        def initialize(document, html_id)
+          @document = document
+          @tag, @operation_id = html_id.split('_')
+          @slug = document.slug + '/' + html_id
+        end
+
+        def swagger_class
+          return @swagger_class if defined?(@swagger_class)
+          @swagger_class = Class.new(Apress::Documentation::Swagger::Schema)
+          @swagger_class.document_slug = document.slug
+          @swagger_class
+        end
+
+        def as_json(options = {})
+          json = super(options)
+
+          json[:slug] = slug
+
+          if view = options[:view]
+            json[:depends_on] = Apress::Documentation::DependencyPresenter.new(view, self).render_deps
+            json[:consumers] = Apress::Documentation::DependencyPresenter.new(view, self).render_deps(reverse: true)
+          end
+
+          json
+        end
+
+        def current_module
+          Apress::Documentation::Storage::Modules.instance[document.slug.to_s.split('/').first]
+        end
+      end
+    end
+  end
+end

data/lib/apress/documentation/swagger/schema.rb

@@ -0,0 +1,39 @@
+module Apress
+  module Documentation
+    module Swagger
+      class Schema
+        include ::Swagger::Blocks
+
+        class << self
+          attr_accessor :resource, :document_slug, :schema_block
+        end
+
+        def self.schema_name(name)
+          "#{self.name}::#{name.to_s.camelize}".to_sym
+        end
+
+        def self.swagger_classes
+          @swagger_classes ||= []
+        end
+
+        def self.inherited(child)
+          swagger_classes << child
+        end
+
+        module Extensions
+          def swagger_path(*args, &block)
+            self.resource = true
+            super
+          end
+
+          def swagger_schema(*args, &block)
+            self.schema_block = block
+            super
+          end
+        end
+
+        singleton_class.prepend Extensions
+      end
+    end
+  end
+end

data/lib/apress/documentation/version.rb

@@ -0,0 +1,5 @@
+module Apress
+  module Documentation
+    VERSION = "0.4.0".freeze
+  end
+end

data/spec/app/controllers/documents_controller_spec.rb

@@ -0,0 +1,42 @@
+require 'spec_helper'
+
+def form_params(p)
+  if Rails::VERSION::MAJOR > 4
+    {params: p}
+  else
+    p
+  end
+end
+
+describe Apress::Documentation::DocumentsController, type: :controller do
+  after do
+    Apress::Documentation.data.clear
+  end
+
+  describe '#show' do
+    before do
+      Apress::Documentation.build(:docs) do
+        document(:doc1, title: 'test')
+      end
+    end
+
+    context 'without params' do
+      it 'response with 200' do
+        get :show
+
+        expect(assigns(:document)).to be_nil
+        expect(response).to have_http_status(:ok)
+      end
+    end
+
+    context 'with path' do
+      it 'response with 200' do
+        get :show, form_params(path: 'docs/doc1')
+
+        expect(assigns(:document).title).to eq 'test'
+
+        expect(response).to have_http_status(:ok)
+      end
+    end
+  end
+end

data/spec/app/controllers/swagger_controller_spec.rb

@@ -0,0 +1,46 @@
+require 'spec_helper'
+
+def form_params(p)
+  if Rails::VERSION::MAJOR > 4
+    {params: p}
+  else
+    p
+  end
+end
+
+describe Apress::Documentation::SwaggerController, type: :controller do
+  describe '#show' do
+    it 'response with 200' do
+      get :show
+
+      expect(response).to have_http_status(:ok)
+    end
+
+    context 'with params' do
+      it 'response ok' do
+        get :show, form_params(module: 'somemodule')
+
+        expect(response).to have_http_status(:ok)
+      end
+    end
+
+    context 'with cache' do
+      around do |example|
+        begin
+          Rails.application.config.action_controller.perform_caching = true
+          example.run
+        ensure
+          Rails.application.config.action_controller.perform_caching = false
+        end
+      end
+
+      it 'caches documentation json' do
+        spy = Apress::Documentation::SwaggerJsonBuilder.new(nil)
+        allow(Apress::Documentation::SwaggerJsonBuilder).to receive(:new).and_return(spy)
+        expect(spy).to receive(:call).once.and_call_original
+        get :show
+        get :show
+      end
+    end
+  end
+end

data/spec/app/controllers/swagger_ui_controller_spec.rb

@@ -0,0 +1,11 @@
+require 'spec_helper'
+
+describe Apress::Documentation::SwaggerUiController, type: :controller do
+  describe '#show' do
+    it 'response with 200' do
+      get :show
+
+      expect(response).to have_http_status(:ok)
+    end
+  end
+end

data/spec/app/services/swagger_json_builder_spec.rb

@@ -0,0 +1,41 @@
+require 'spec_helper'
+
+RSpec.describe Apress::Documentation::SwaggerJsonBuilder, type: :service do
+  describe '#call' do
+    let(:service) { described_class.new(slug) }
+    before do
+      klass = Class.new(Apress::Documentation::Swagger::Schema) do
+        swagger_path 'api/test' do
+          operation :get
+        end
+      end
+      klass.document_slug = slug
+
+      Class.new(Apress::Documentation::Swagger::Schema) do
+        swagger_path 'api/test2' do
+          operation :get
+        end
+      end
+    end
+
+    context 'when slug is present' do
+      let(:slug) { 'test' }
+
+      it 'filters paths' do
+        data = service.call[:paths]
+        expect(data).to include :"api/test"
+        expect(data).not_to include :"api/test2"
+      end
+    end
+
+    context 'without slug' do
+      let(:slug) { nil }
+
+      it 'returns all data' do
+        data = service.call[:paths]
+        expect(data).to include :"api/test"
+        expect(data).to include :"api/test2"
+      end
+    end
+  end
+end

data/spec/apress/documentation_spec.rb

@@ -0,0 +1,342 @@
+require "spec_helper"
+
+RSpec.describe Apress::Documentation do
+  context 'simple build call' do
+    before do
+      Apress::Documentation.build(:doc) do
+        title 'name'
+        description 'description'
+        publicity :public
+        tests 'tests'
+      end
+    end
+
+    it 'create document' do
+      expect(Apress::Documentation.data.size).to eq 1
+      doc = Apress::Documentation.data['doc']
+      expect(doc.title).to eq 'name'
+      expect(doc.description).to eq 'description'
+      expect(doc.publicity).to eq 'Публичный'
+      expect(doc.tests).to eq 'tests'
+    end
+  end
+
+  context 'without block call' do
+    before do
+      Apress::Documentation.build(
+        :doc,
+        title: 'some',
+        description: 'test'
+      )
+    end
+
+    it 'create document' do
+      expect(Apress::Documentation.data.size).to eq 1
+      doc = Apress::Documentation.data['doc']
+      expect(doc.title).to eq 'some'
+      expect(doc.description).to eq 'test'
+    end
+  end
+
+  context 'when documents is nesting' do
+    before do
+      Apress::Documentation.build(:doc) do
+        document(:doc1) do
+          title 'cool document'
+
+          document(:doc2) do
+            title 'cool document 2'
+          end
+        end
+      end
+    end
+
+    it 'create all documents' do
+      expect(Apress::Documentation.data.size).to eq 1
+      doc = Apress::Documentation.data['doc'].documents['doc1']
+      expect(doc.title).to eq 'cool document'
+      expect(doc.documents['doc2'].title).to eq 'cool document 2'
+    end
+  end
+
+  context 'when multiple documents in one block call' do
+    before do
+      Apress::Documentation.build(:doc) do
+        document(:doc1) do
+          title 'cool document'
+        end
+
+        document(:doc2) do
+          title 'cool document 2'
+        end
+      end
+    end
+
+    it 'create all documents' do
+      doc = Apress::Documentation.data['doc']
+      expect(doc.documents.size).to eq 2
+      expect(doc.documents['doc1'].title).to eq 'cool document'
+      expect(doc.documents['doc2'].title).to eq 'cool document 2'
+    end
+  end
+
+  context 'when documents rewretes in next block' do
+    before do
+      Apress::Documentation.build(:doc) do
+        document(:doc1) do
+          title 'cool document'
+        end
+
+        document(:doc1) do
+          title 'cool document 2'
+        end
+      end
+    end
+
+    it 'rewrites it' do
+      doc = Apress::Documentation.data['doc']
+      expect(doc.documents.size).to eq 1
+      expect(doc.documents['doc1'].title).to eq 'cool document 2'
+    end
+  end
+
+  context 'when document is swagger' do
+    before do
+      Apress::Documentation.build(:doc) do
+        document(:doc1) do
+          title 'cool document'
+
+          swagger_bind('some_point') do
+            business_desc 'cool document 2'
+
+            swagger_path('api/docs') do
+              operation :get
+            end
+          end
+        end
+      end
+    end
+
+    it 'returns proper json' do
+      doc = Apress::Documentation.data['doc'].documents['doc1']
+      expect(doc.title).to eq 'cool document'
+      expect(doc.swagger_documents.size).to eq 1
+      expect(doc.swagger_documents.as_json).to eq(
+        "some_point" => {"business_desc" => "cool document 2", slug: "doc/doc1/some_point"}
+      )
+    end
+
+    context 'when swagger document is rewritten' do
+      before do
+        Apress::Documentation.build(:doc) do
+          document(:doc1) do
+            title 'cool document'
+
+            swagger_bind('some_point') do
+              tests 'somewhere'
+
+              swagger_path('api/docs') do
+                operation :get
+              end
+            end
+          end
+        end
+      end
+
+      it 'returns proper json' do
+        doc = Apress::Documentation.data['doc'].documents['doc1']
+        expect(doc.title).to eq 'cool document'
+        expect(doc.swagger_documents.size).to eq 1
+        expect(doc.swagger_documents.as_json).to eq(
+          "some_point" => {
+            "business_desc" => "cool document 2",
+            "tests" => "somewhere",
+            slug: "doc/doc1/some_point"
+          }
+        )
+      end
+    end
+
+    context 'when bind point is not defined' do
+      before do
+        Apress::Documentation.build(:swagger_auto) do
+          document(:swagger1) do
+            title 'swagger document'
+
+            swagger_bind do
+              tests 'here'
+
+              swagger_path('api/tests') do
+                operation :get do
+                  key :operationId, 'testIndex'
+                  key :tags, ['tests']
+                end
+              end
+            end
+          end
+        end
+      end
+
+      it 'returns proper json' do
+        doc = Apress::Documentation.data['swagger_auto'].documents['swagger1']
+        expect(doc.title).to eq 'swagger document'
+        expect(doc.swagger_documents.size).to eq 1
+        expect(doc.swagger_documents.as_json).to eq(
+          "tests_testIndex" => {"tests" => "here", slug: "swagger_auto/swagger1/tests_testIndex"}
+        )
+      end
+    end
+
+    context 'when paseed field is unknow' do
+      it 'raises RuntimeError' do
+        expect do
+          Apress::Documentation.build(:module, unexpected_field: 'test')
+        end.to raise_error RuntimeError
+      end
+    end
+  end
+
+  context 'publicity' do
+    context 'when argumens is valid' do
+      it 'set proper value to document' do
+        Apress::Documentation.build(:module) do
+          document(:doc1) do
+            publicity :public
+          end
+        end
+
+        doc = Apress::Documentation.data['module'].documents['doc1']
+
+        expect(doc.publicity).to eq 'Публичный'
+      end
+    end
+
+    context 'when argument is invalid' do
+      it 'raises error' do
+        expect do
+          Apress::Documentation.build(:module) do
+            document(:doc1) do
+              publicity :test
+            end
+          end
+        end.to raise_error("Неизвестный уровень доступа - test, объявлен в документе module/doc1")
+      end
+    end
+  end
+
+  context 'dependencies' do
+    context 'for document' do
+      context 'when refered document exists' do
+        before do
+          Apress::Documentation.build(:module) do
+            document(:doc) do
+              depends_on('module/doc2')
+            end
+
+            document(:doc2)
+          end
+        end
+
+        it 'build dependency' do
+          doc = Apress::Documentation.data['module'].documents['doc']
+          doc2 = Apress::Documentation.data['module'].documents['doc2']
+          expect(doc.dependencies).to include [doc, doc2]
+        end
+      end
+
+      context 'when refered document does exists' do
+        before do
+          Apress::Documentation.build(:module) do
+            document(:doc) do
+              depends_on('module/doc2')
+            end
+          end
+        end
+
+        it 'is not valid' do
+          doc = Apress::Documentation.data['module'].documents['doc']
+          expect { Apress::Documentation.validate_dependencies! }.
+            to raise_error("Несуществующий документ - module/doc2, объявлен в - [#{doc.inspect}]")
+        end
+      end
+    end
+
+    context 'for swagger_document' do
+      context 'when refered document exists' do
+        before do
+          Apress::Documentation.build(:module) do
+            document(:doc) do
+              depends_on('module/doc2')
+            end
+
+            document(:doc2)
+          end
+        end
+
+        it 'build dependency' do
+          doc = Apress::Documentation.data['module'].documents['doc']
+          doc2 = Apress::Documentation.data['module'].documents['doc2']
+          expect(doc.dependencies).to include [doc, doc2]
+        end
+      end
+
+      context 'when refered document does exists' do
+        before do
+          Apress::Documentation.build(:module) do
+            document(:doc) do
+              depends_on('module/doc2')
+            end
+          end
+        end
+
+        it 'is not valid' do
+          doc = Apress::Documentation.data['module'].documents['doc']
+          expect { Apress::Documentation.validate_dependencies! }.
+            to raise_error("Несуществующий документ - module/doc2, объявлен в - [#{doc.inspect}]")
+        end
+      end
+    end
+  end
+
+  describe '#fetch_document' do
+    before do
+      Apress::Documentation.build(:module) do
+        document(:doc1) do
+          document(:doc2) do
+            document(:doc3) do
+              title 'test'
+            end
+          end
+        end
+      end
+    end
+
+    it 'fetches document by path' do
+      expect(Apress::Documentation.fetch_document('module/doc1/doc2/doc3').title).to eq 'test'
+    end
+  end
+
+  describe '#add_load_path' do
+    it 'loads all docs in folder on callback run' do
+      Apress::Documentation.add_load_path(Rails.root.join('lib/stub_docs'))
+
+      ActiveSupport.run_load_hooks(:documentation)
+
+      module_document = Apress::Documentation.data['test_load_module']
+      expect(module_document.description).to eq 'Cool module'
+      expect(module_document.documents['document'].documents['child'].description).to eq 'Cool document'
+    end
+  end
+
+  context 'config' do
+    it 'has default path scope' do
+      expect(subject.fetch(:path_scope)).to be_nil
+    end
+
+    it 'applies changes' do
+      expect { subject[:path_scope] = :cosmos }
+        .to change { subject.fetch(:path_scope) }
+        .from(nil).to(:cosmos)
+    end
+  end
+end