swagger-doc-rails 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: ed7aba823f2b20ecc0ff55b80b3ac4599ca5c3a1
+  data.tar.gz: 06da8e3f9423c2bb114da219e76b58956e957a09
+SHA512:
+  metadata.gz: aec7c12e5806c1bc9056b07d6c11841b12053ac73766ad41d8027bc962f11ae6ed6592db15900a3e57c3f9c362fea54880987961ef62c5266eba43562d90e721
+  data.tar.gz: f0ad066914f44470bea5176b300be91900498d6f454e48fbfb672a525f709a656ef101c8ff9b4fc163cfa4ac6664ab1190b4d9f76435e80b973ad2ceb558b72a

data/.gitignore

@@ -0,0 +1,18 @@
+*.gem
+*.rbc
+.bundle
+.config
+.yardoc
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp
+public

data/Appraisals

@@ -0,0 +1,7 @@
+appraise "rails-3" do
+  gem "rails", "~> 3.2.16"
+end
+
+appraise "rails-4" do
+  gem "rails", "~> 4.0.0"
+end

data/CHANGELOG.md

@@ -0,0 +1,120 @@
+## 0.2.9
+
+Fix gem dependencies to support Rails 5 #141
+
+## 0.2.8
+
+Accept success status (#134) - thanks to @dcarneiro
+
+## 0.2.7
+
+- Fix issue "NoMethodError: undefined method `<' for false:FalseClass" (#133) - thanks to @heaven
+
+## 0.2.6
+
+- swagger_controller DSL can accept a resource_path which will be used over a generated path #126 @sb8244
+
+## 0.2.5
+
+- Enabled option to set 'items' inside swagger_api method #99 @krakatoa
+
+## 0.2.4
+
+- Parent controller option for register_apis config. #123 @mskubenich
+
+## 0.2.3
+
+- Added property_list to SwaggerModelDSL #108 @dr-impossible
+
+## 0.2.2
+
+- Support multiple route methods #128 @frodrigo
+
+## 0.2.1
+
+- Add support for Authorizations (OAuth 2.0) - Thanks to @RKushnir #97
+
+## 0.2.0
+
+- Additional logging for generation failures (suggested in #81)
+- Added api_file_name to config #88
+- Add support for multiple base api controllers. #93
+- Change success status to ok #89
+- Address issue with missing slashes - remove trailing slash from base paths and add slash before api paths #117
+
+## 0.1.9
+
+- Adding support for multiple engines #65
+- Add ability for swagger_api to accept parameters (e.g. consumes, produces)
+- Update dependencies #64
+- Address issue with routing verbs where some verbs do not have a route.verb.source attribute only route.verb #58
+- Add ability to set custom attributes (like info block) on api-docs file #67
+- Ensure API endpoint/nickname (e.g. "Api::V1::Some#update") is only written out once per resource file. Addresses PATCH, POST duplication issue #70
+- Add "consumes" dsl method #74
+- Expose API version on transform_path for easier “No Server Integrations” #79
+
+## 0.1.8
+
+- Fix issue with gem build open-ended dependency warnings in gemspec
+- Fix issue where param_list doesn't output parameter description #57
+
+## 0.1.7
+
+- Make camelizing of model properties configurable. #55
+
+## 0.1.6
+
+- Document notes DSL
+- Get rid of unnecessary ternary operator in dsl.rb #54
+- Fix development dependencies gems requirements #53
+- Add support for the `notes` property #52
+- Config's base_api_controller is configurable #51
+
+## 0.1.5
+- Delay processing docs DSL to allow changing the context of the controllers #47 @ldnunes
+
+## 0.1.4
+- An undocumentated action in a documented controller should not raise errors #43 @ldnunes
+- Allow reopening of docs definition for the swagger_api DSL command #44 @ldnunes
+- Refactor write_docs to split the documentation generation from file writing #45 @ldnunes
+
+## 0.1.3
+- Fix issue where empty path throws error
+
+## 0.1.2
+- Add suport for Swagger models
+- Use ActionControlller::Base instead of ApplicationController. fixes #27
+- Status codes for response
+- Path generation fixes #26 @stevschmid
+- Ignore path filtering when no params are set
+- Add param_list helper for generating enums/lists
+- Improve structure of generator class - break up large methods
+- Fix the destination path of the resource files #30
+
+## 0.1.1
+- Add support for Rails engines (@fotinakis)
+- Filter out path parameters if the parameter is not in the path (@stevschmid)
+
+## 0.1.0
+
+- Add CHANGELOG.md
+- Add `api_extension_type` option (support for other route .formats)
+- Rails Appraisals
+- Add configuration options table to README documentation
+- Guidance on inheritance and asset pre-compilation
+- Custom response message error text can now be set
+- Ability to override base controller with `base_api_controller` method
+- Default configuration for Generator
+- Fix typo in README.md
+
+##0.0.3
+
+- Documentation 
+
+## 0.0.2 
+
+- Add `base_path` option
+
+## 0.0.1 
+
+- Initial release

data/Gemfile

@@ -0,0 +1,4 @@
+# source 'https://rubygems.org'
+source 'http://gems.ruby-china.com/'
+# Specify your gem's dependencies in swagger-docs.gemspec
+gemspec

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2019 zxhe
+
+MIT License
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,448 @@
+# Swagger::Docs::Rails
+copied from [@swagger-docs](https://github.com/richhollis/swagger-docs)
+
+Generates swagger-ui json files for rails apps with APIs. You add the swagger DSL to your controller classes and then run one rake task to generate the json files.
+
+[gem]: https://rubygems.org/gems/swagger-docs
+
+## Swagger Version Specification Support
+
+This project supports elements of the v2.0 swagger specification. only simple function v2.0 specification. not yet realize senior function, but is enough to generate api docs for rails project, and just need to declare paraneters then anything other is same with a rails project. I'm open to accepting a PR on  this. Contact me if you are interested in helping with that effort - thanks!
+
+## Example usage
+
+Here is an extract of the DSL from a user controller API class:
+
+```ruby
+swagger_controller :users, "User Management"
+
+swagger_api :index do
+  summary "Fetches all User items"
+  notes "This lists all the active users"
+  param :query, :page, :integer, :required, "Page number"
+end
+def index
+  # do anything like you do in rails
+  render json: {status: 200, msg: 'ok', data: {page_num: params[:page]}}
+end
+
+swagger_api :create do
+  summary "create a user"
+  param :query, :nickname, :string, :required, "nickname"
+  param_list :query, :gender, :string, :required, "gender", [ "male", "female" ]
+  param :query, :email, :string, :required, "email"
+  param :query, :phone, :string, :required, "phone"
+  response :unauthorized
+  response :not_acceptable
+end
+def create
+  # do anything like you do in rails
+  render json: {
+    status: 200,
+    msg: 'ok',
+    data: {
+      nickname: params[:nickname],
+      gender: params[:gender],
+      email: params[:email],
+      phone: params[:phone]
+    }
+  }
+end
+```
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+    gem 'swagger-doc-rails'
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install swagger-doc-rails
+
+## Usage
+
+### Create Initializer
+
+Create an initializer in config/initializers (e.g. swagger_docs.rb) and define your APIs:
+
+```ruby
+Swagger::Docs::Config.register_apis({
+  "1.0" => {
+    # the extension used for the API
+    :api_extension_type => :json,
+    # the output location where your .json files are written to
+    :api_file_path => "public",
+    # the URL base path to your API
+    :host => "localhost:3000",
+    # if you want to delete all .json files at each generation
+    :clean_directory => true,
+    # # Ability to setup base controller for each api version. Api::V1::SomeController for example.
+    :parent_controller => Api::ApplicationController,
+
+    :controller_base_path => 'api/',
+    # # add custom attributes to api-docs
+    :attributes => {
+      :info => {
+        "title" => "Swagger test",
+        "version" => '1.0.0',
+        "description" => "siple description.",
+      }
+    }
+  }
+})
+```
+
+#### Configuration options
+
+The following table shows all the current configuration options and their defaults. The default will be used if you don't supply your own value.
+
+<table>
+<thead>
+<tr>
+<th>Option</th>
+<th>Description</th>
+<th>Default</th>
+</tr>
+</thead>
+<tbody>
+
+<tr>
+<td><b>api_extension_type</b></td>
+<td>The extension, if necessary, used for your API - e.g. :json or :xml </td>
+<td>nil</td>
+</tr>
+
+<tr>
+<td><b>api_file_path</b></td>
+<td>The output file path where generated swagger-docs files are written to. </td>
+<td>public/</td>
+</tr>
+
+<tr>
+<td><b>base_path</b></td>
+<td>The URI base path for your API - e.g. api.somedomain.com</td>
+<td>/</td>
+</tr>
+
+<tr>
+<td><b>base_api_controller / base_api_controllers</b></td>
+<td>The base controller class your project uses; it or its subclasses will be where you call swagger_controller and swagger_api. An array of base controller classes may be provided.</td>
+<td>ActionController::Base</td>
+</tr>
+
+<tr>
+<td><b>clean_directory</b></td>
+<td>When generating swagger-docs files this option specifies if the api_file_path should be cleaned first. This means that all files will be deleted in the output directory first before any files are generated.</td>
+<td>false</td>
+</tr>
+
+<tr>
+<td><b>formatting</b></td>
+<td>Specifies which formatting method to apply to the JSON that is written. Available options: :none, :pretty</td>
+<td>:pretty</td>
+</tr>
+
+<tr>
+<td><b>camelize_model_properties</b></td>
+<td>Camelizes property names of models. For example, a property name called first_name would be converted to firstName.</td>
+<td>true</td>
+</tr>
+
+<tr>
+<td><b>parent_controller</b></td>
+<td>Assign a different controller to use for the configuration</td>
+<td></td>
+</tr>
+
+</tbody>
+</table>
+
+#### Custom resource paths`(PR #126)
+
+```ruby
+class Api::V1::UsersController < ApplicationController
+
+  swagger_controller :users, "User Management", resource_path: "/some/where"
+```
+
+### DRYing up common documentation
+
+Suppose you have a header or a parameter that must be present on several controllers and methods. Instead of duplicating it on all the controllers you can do this on your API base controller:
+
+```ruby
+class Api::BaseController < ActionController::Base
+  class << self
+    Swagger::Docs::Generator::set_real_methods
+
+    def inherited(subclass)
+      super
+      subclass.class_eval do
+        setup_basic_api_documentation
+      end
+    end
+
+    private
+    def setup_basic_api_documentation
+      [:index, :show, :create, :update, :delete].each do |api_action|
+        swagger_api api_action do
+          param :header, 'Authentication-Token', :string, :required, 'Authentication token'
+        end
+      end
+    end
+  end
+end
+```
+
+### Run rake task to generate docs
+
+```
+rake swagger:docs
+```
+
+Swagger-ui JSON files should now be present in your api_file_path (e.g. ./public/api/)
+
+#### Additional logging for generation failures
+
+Errors aren't displayed by default. To see all error messages use the ```SD_LOG_LEVEL``` environment variable when running the rake task:
+
+```
+SD_LOG_LEVEL=1 rake swagger:docs
+```
+
+Currently only constantize errors are shown.
+
+Errors are written to ```$stderr```. Error logging methods can be found in ```Config``` and can be overridden for custom behaviour.
+
+### Advanced Customization
+
+#### Inheriting from a custom Api controller
+
+By default swagger-docs is applied to controllers inheriting from ApplicationController.
+If this is not the case for your application, use this snippet in your initializer
+_before_ calling Swagger::Docs::Config#register_apis(...).
+
+```ruby
+class Swagger::Docs::Config
+  def self.base_api_controller; Api::ApiController end
+end
+```
+
+#### Custom route discovery for supporting Rails Engines
+
+By default, swagger-docs finds controllers by traversing routes in `Rails.application`.
+To override this, you can customize the `base_application` config in an initializer:
+
+```ruby
+class Swagger::Docs::Config
+  def self.base_application; Api::Engine end
+end
+```
+
+If you want swagger to find controllers in `Rails.application` and/or multiple
+engines you can override `base_application` to return an array.
+
+```ruby
+class Swagger::Docs::Config
+  def self.base_application; [Rails.application, Api::Engine, SomeOther::Engine] end
+end
+```
+
+Or, if you prefer you can override `base_applications` for this purpose. The plural
+`base_applications` takes precedence over `base_application` and MUST return an
+array.
+
+```ruby
+class Swagger::Docs::Config
+  def self.base_applications; [Rails.application, Api::Engine, SomeOther::Engine] end
+end
+```
+
+#### Transforming the `path` variable
+
+Swagger allows a distinction between the API documentation server and the hosted API
+server through the `path` variable (see [Swagger: No server Integrations](https://github.com/wordnik/swagger-core/wiki/No-server-Integrations)). To override the default swagger-docs behavior, you can provide a `transform_path`
+class method in your initializer:
+
+```ruby
+class Swagger::Docs::Config
+  def self.transform_path(path, api_version)
+    "http://example.com/api-docs/#{api_version}/#{path}"
+  end
+end
+```
+
+The transformation will be applied to all API `path` values in the generated `api-docs.json` file.
+
+#### Precompile
+
+It is best-practice *not* to keep documentation in version control. An easy way
+to integrate swagger-docs into a conventional deployment setup (e.g. capistrano,
+chef, or opsworks) is to piggyback on the 'assets:precompile' rake task. And don't forget
+to add your api documentation directory to .gitignore in this case.
+
+```ruby
+#Rakefile or lib/task/precompile_overrides.rake
+namespace :assets do
+  task :precompile do
+    Rake::Task['assets:precompile'].invoke
+    Rake::Task['swagger:docs'].invoke
+  end
+end
+```
+
+### Output files
+
+api-docs.json output:
+
+```json
+{
+  "swagger": "2.0",
+  "host": "localhost:3000",
+  "basePath": "/api/",
+  "schemes": [
+    "http"
+  ],
+  "paths": {
+    "/users": {
+      "get": {
+        "summary": "Fetches all User items",
+        "description": "User Management",
+        "parameters": [
+          {
+            "name": "page",
+            "in": "query",
+            "required": true,
+            "description": "Page number",
+            "type": "integer"
+          },
+          {
+            "name": "nested_id",
+            "in": "query",
+            "required": true,
+            "description": "Team Id",
+            "type": "integer"
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "User Management",
+            "schema": {
+            }
+          }
+        }
+      }
+    },
+    "/users/": {
+      "post": {
+        "summary": "创建一个新用户",
+        "description": "User Management",
+        "parameters": [
+          {
+            "name": "nickname",
+            "in": "query",
+            "required": true,
+            "description": "昵称",
+            "type": "string"
+          },
+          {
+            "name": "gender",
+            "in": "query",
+            "required": true,
+            "description": "性别",
+            "type": "string"
+          },
+          {
+            "name": "email",
+            "in": "query",
+            "required": true,
+            "description": "邮箱",
+            "type": "string"
+          },
+          {
+            "name": "phone",
+            "in": "query",
+            "required": true,
+            "description": "手机",
+            "type": "string"
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "User Management",
+            "schema": {
+               "type": "pbject",
+               "items": {
+                 "properties": {
+                   "nickname": {
+                       "type": "string"
+                   },
+                   "gender": {
+                       "type": "string"
+                   },
+                  "email": {
+                       "type": "string"
+                   },
+                  "phone": {
+                       "type": "string"
+                   }
+                 }
+               }
+            }
+          }
+        }
+      }
+    },
+    "/users/{id}": {
+      "get": {
+        "summary": "Fetches a single User item",
+        "description": "User Management",
+        "parameters": [
+          {
+            "name": "id",
+            "in": "path",
+            "required": false,
+            "description": "User Id",
+            "type": "integer"
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "User Management",
+            "schema": {
+            }
+          }
+        }
+      }
+    },
+  },
+  "info": {
+    "title": "Swagger test",
+    "version": "1.0.0",
+    "description": "simple description."
+  }
+}
+
+```
+
+## Thanks to our contributors
+
+Welcome contributors for making swagger-doc-railss even better.
+
+## Related Projects
+
+**[@fotinakis](https://github.com/richhollis/swagger-docs)**
+
+## Contributing
+
+When raising a Pull Request please ensure that you have provided good test coverage for the request you are making.
+
+1. Fork it
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create new Pull Request