openapi-rails 0.3.0 → 0.3.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 4c59c89fba1f2018b1a64be627710bf6f3bfdea7
-  data.tar.gz: c913517ac8e3f9111f7c6df93bceb32a9565df25
+  metadata.gz: 7de2269c948f0ee5b643d6508f87551181bec70c
+  data.tar.gz: 7b2f7b0279fa82108b3aafcaa7a52743991c5a90
 SHA512:
-  metadata.gz: 01bcda62e4d144fed5d03b213693d0cbf00a5df5cab518dd46511d753309fdee6309967249fe319b5b7f21cfbaf4202aa6c57d20c4cfcbbbf8ef93e1369cf3a0
-  data.tar.gz: 5363c1889eb1245ec444273804822dae79f994b6e9cc6556dd4e8ea67c3ebddf101d6ff903c3476adec91009ea5a24291e7701a942729a82c962fa270696ce3b
+  metadata.gz: 344fd7b1b01c77d22bda310dd0ccbcc9719260e5b09e7e5a27cebbc68819b2f3c9e101b3a333045cfbb9ff1e5923f6cb4e4dbb7f09160861cc2130a98e48d843
+  data.tar.gz: 658ff23bab20e35dbdfe7e128b014abf73818d8349192f3ded01539315e189ca8aaf798279f407fba5f294e70312d65629d7b6c8cb62c797d0ac13095bbb6bfd

data/README.md

@@ -1,4 +1,6 @@
-<img src="http://www.kra.vc/_Media/swagger-logo.png" align="right" width="90px" />
+<img src="http://www.kra.vc/_Media/swagger-logo.png" align="right" width="100px" />
+
+[![Gem Version](https://badge.fury.io/rb/openapi-rails.svg)](https://badge.fury.io/rb/openapi-rails)
 
 # OpenAPI
 
@@ -6,13 +8,15 @@ CRUD interface for Rails models with OpenAPI ([Swagger](http://swagger.io/))
 specification support and [Swagger UI](http://swagger.io/swagger-ui/)
 integration.
 
+**This gem supports only Mongoid, for other ORMs RPs are welcome.**
+
 
 ## Installation
 
 Add to your `Gemfile`:
 
 ```ruby
-gem 'openapi'
+gem 'openapi-rails'
 ```
 
 For new projects we recommend to run generator to create basic setup:
@@ -21,41 +25,202 @@ For new projects we recommend to run generator to create basic setup:
 rake g openapi:config
 ```
 
+If you have an existing project, please look through this readme file first to
+get an idea of how it works.
+
+Generator is creating configuration file `config/initializer/openapi.rb` with
+default `/api` configuration and base controller `app/controllers/api/base_controlle.rb` that provides CRUD actions and specification builder.
+
 
 ## Usage
 
+*Here projects API considered to be available at `/api`. Please check out
+[Multiple APIs](#multiple-apis) section for other options.*
+
+To add `CRUD` interface for the `Project` model create an empty controller that
+inherits from `BaseController` at `app/controllers/api/projects_controller.rb`:
+
+```ruby
+module Api
+  class ProjectsController < BaseController
+  end
+end
+```
+
+Map controller with `crud` helper, mount specification and documentation in
+`routes.rb`:
+
+```ruby
+Rails.application.routes.draw do
+  namespace :api do
+    crud :projects
+    # Mount OpenAPI specification for API
+    mount_openapi_specification name: :default
+  end
+
+  # Mount Swagger UI documentation for API
+  mount_openapi_documentation
+end
+```
+
+Add `Api::ProjectsController` to `config/initializer/openapi.rb` controllers
+arrays of the default configuration:
+
+```ruby
+Openapi.configure do |config|
+  config.apis = {
+    default: {
+      title: 'Default',
+      description: '',
+      version: '1.0',
+      base_path: '/api',
+      controllers: [Api::ProjectsController]
+    }
+  }
+end
+```
+
+Restart develoment server and open [http://localhost:3000/openapi](http://localhost:3000/openapi) where API documentation is served.
+
+![OpenAPI Rails Demo](https://d3vv6lp55qjaqc.cloudfront.net/items/262y2S3Q3N0u14160a20/openapi-rails-demo.png)
+
+Meta information about mapped actions and model fields is pulled automatically
+on project initialization. Changes in `routes.rb` or models would require server
+restart to be reflected in documentation.
 
-## CSV
+In documentation interface for `create` and `update` actions request `Example
+Value` includes only required fields. Other model fields should be added
+manually.
 
 
-## Default Index
+## Supported Features
 
- - _id
+Following features are supported out of the box:
+
+  - pagination via [kaminari](https://github.com/amatsuda/kaminari)
+  - has_scope via [has_scope](https://github.com/plataformatec/has_scope)
+  - search via [mongoid-search](https://github.com/mauriciozaffari/mongoid_search)
+  - version via [mongoid-history](https://github.com/aq1018/mongoid-history)
+  - `CSV` format for `index` action, requires `.csv` format to be added to the
+    request url, e.g. `/api/posts.csv`.
 
 
 ## Customization
 
- - json
- - has_scope
- - per_page
- - resource_class
+In the controller there is a way override default behaviour with helpers:
+
+  - `per_page` — set page size (default `50`) for `index` action
+  - `resource_class` — set model class manually
+  - `resource_params` — override default method that allows everything
 
 
 ## Custom Actions
 
- - warning
- - building spec for custom actions
+Mapped custom actions (not CRUD) will add a log message on server start that
+controller misses specification. As a result they are not added to
+documentation.
+
+Specification for custom methods should be added manually. Check out
+[Swagger Blocks](https://github.com/fotinakis/swagger-blocks) gem or
+[specification builder](https://github.com/slate-studio/openapi-rails/blob/master/lib/openapi/mongoid/spec_builder.rb) code for the reference.
+
+Here is an example of custom method specification:
+
+```ruby
+module Api
+  class ProjectsController < BaseController
+    def custom_resource_action
+      # TODO: Method implemetation goes here.
+    end
+
+    swagger_path "/projects/{id}/custom_resource_action" do
+      operation :get do
+        key :tags,        ["Projects"]
+        key :summary,     'Show extra details'
+        key :operationId, "showExtraProjectDetailsById"
+        key :produces,    %w(application/json)
+
+        parameter do
+          key :name,     :id
+          key :type,     :string
+          key :in,       :path
+          key :required, true
+        end
+
+        response 200 do
+          schema do
+            key :'$ref', "Project"
+          end
+        end
+      end
+    end
+  end
+end
+```
 
 
 ## Multiple APIs
 
- - configuration options
+There is a clean way to provide multiple APIs or API versions.
+
+Here is an example of setting up two API versions:
+
+`config/routes.rb`:
+
+```ruby
+Rails.application.routes.draw do
+  namespace :api do
+    namespace :v1 do
+      crud :projects
+      mount_openapi_specification name: :v1
+    end
+
+    namespace :v2 do
+      crud :projects
+      mount_openapi_specification name: :v2
+    end
+  end
+
+  mount_openapi_documentation
+end
+```
+
+`config/initializer/openapi.rb`:
+
+```ruby
+Openapi.configure do |config|
+  config.apis = {
+    v1: {
+      title: 'Version 1',
+      description: 'Legacy API version, please check out Version 2.',
+      version: '1.0',
+      base_path: '/api/v1',
+      controllers: [Api::V1::ProjectsController]
+    },
+    v2: {
+      title: 'Version 2',
+      description: 'Latest stable API version.',
+      version: '2.0',
+      base_path: '/api/v2',
+      controllers: [Api::V2::ProjectsController]
+    }
+  }
+end
+```
+
+Controllers with custom logic would be placed at `app/controllers/api/v1` and
+`app/controllers/api/v2` modules.
+
+![OpenAPI Rails — Multiple versions demo](http://files.slatestudio.com/hJjg/openapi-rails-multiple-versions.png)
+
 
+## Contributors
 
-## Authors
+ - [Alexander Kravets](http://www.kra.vc)
+ - [Denis Popov](https://github.com/DenisPopov15)
 
- - Alexander Kravets
- - Denis Popov
+If you have any ideas or questions please feel free to reach out! PRs are
+welcome, tests are on the roadmap.
 
 
-[Slate Studio](https://www.slatestudio.com)
+`OpenAPI Rails` gem is maintained and funded by [Slate Studio LLC](https://www.slatestudio.com).

data/lib/openapi/mongoid/crud_actions.rb

@@ -206,22 +206,6 @@ module Openapi
       end
 
       class_methods do
-        def index_json_config(hash)
-          self.index_json_config = hash
-        end
-
-        def create_json_config(hash)
-          self.create_json_config = hash
-        end
-
-        def show_json_config(hash)
-          self.show_json_config = hash
-        end
-
-        def update_json_config(hash)
-          self.update_json_config = hash
-        end
-
         def resource_class(name)
           self.resource_class = name
         end

data/lib/openapi/version.rb

@@ -1,3 +1,3 @@
 module Openapi
-  VERSION = '0.3.0'.freeze
+  VERSION = '0.3.1'.freeze
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: openapi-rails
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.3.1
 platform: ruby
 authors:
 - Alexander Kravets