gitlab-grape-swagger 1.5.0

data/RELEASING.md

@@ -0,0 +1,82 @@
+# Releasing Grape-Swagger
+
+There are no particular rules about when to release grape-swagger. Any co-maintainer is encouraged to release bug fixes frequently, features not so frequently and breaking API changes rarely.
+
+### Release
+
+Run tests, check that all tests succeed locally.
+
+```
+bundle install
+rake
+```
+
+Check that the last build succeeded in [Travis CI](https://travis-ci.org/ruby-grape/grape-swagger) for all supported platforms.
+
+Change "Next" in [CHANGELOG.md](CHANGELOG.md) to the current date.
+
+```
+### 0.7.2 (February 6, 2014)
+```
+
+Remove the lines with "Your contribution here.", since there will be no more contributions to this release.
+
+Commit your changes.
+
+```
+git add CHANGELOG.md lib/grape-swagger/version.rb
+git commit -m "Preparing for release, 0.7.2."
+git push origin master
+```
+
+Release.
+
+```
+$ rake release
+
+grape-swagger 0.7.2 built to pkg/grape-swagger-0.7.2.gem.
+Tagged v0.7.2.
+Pushed git commits and tags.
+Pushed grape-swagger 0.7.2 to rubygems.org.
+```
+
+### Prepare for the Next Version
+
+Increment the minor version, the third number, modify [lib/grape-swagger/version.rb](lib/grape-swagger/version.rb). For example, change `0.7.1` to `0.7.2`. Major versions are incremented in pull requests that require it.
+
+Add the next release to [CHANGELOG.md](CHANGELOG.md).
+
+```
+### 0.7.3 (Next)
+
+#### Features
+
+* Your contribution here.
+
+#### Fixes
+
+* Your contribution here.
+```
+
+Commit your changes.
+
+```
+git add CHANGELOG.md lib/grape-swagger/version.rb
+git commit -m "Preparing for next developer iteration, 0.7.3."
+git push origin master
+```
+
+### Make an Announcement
+
+Make an announcement on the [ruby-grape@googlegroups.com](mailto:ruby-grape@googlegroups.com) mailing list. The general format is as follows.
+
+```
+Grape-Swagger 0.7.2 has been released.
+
+There were 8 contributors to this release, not counting documentation.
+
+Please note the breaking API change in ...
+
+[copy/paste CHANGELOG here]
+
+```

data/Rakefile

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+require 'rubygems'
+require 'bundler'
+
+Bundler.setup(:default, :development)
+
+require 'rake'
+
+Bundler::GemHelper.install_tasks
+
+require 'rspec/core'
+require 'rspec/core/rake_task'
+
+RSpec::Core::RakeTask.new(:spec)
+
+require 'rubocop/rake_task'
+RuboCop::RakeTask.new(:rubocop)
+
+task default: %i[spec rubocop]

data/UPGRADING.md

@@ -0,0 +1,201 @@
+## Upgrading Grape-swagger
+
+### Upgrading to >= 1.5.0
+
+- The names generated for body parameter definitions and their references has changed. It'll now include the HTTP action as well as any path parameters.
+  - E.g, given a `PUT /things/:id` endpoint, `paths.things/{id}.put.parameters` in the generated Swaggerfile will contain the following:
+  - With `grape-swagger < 1.5.0`: `{ "name": "Things", ..., "schema": { "$ref": "#/definitions/putThings" } }`
+  - With `grape-swagger >= 1.5.0`: `{ "name": "putThingsId", ..., "schema": { "$ref": "#/definitions/putThingsId" } }`
+- If you use the `nickname` option for an endpoint, that nickname will be used for both the parameter name and its definition reference.
+  - E.g., if the endpoint above were nicknamed `put-thing`, the generated Swaggerfile will contain `{ "name": "put-thing", ..., "schema": { "$ref": "#/definitions/put-thing" } }`
+
+
+### Upgrading to >= 1.4.2
+
+- `additionalProperties` has been deprecated and will be removed in a future version of `grape-swagger`. It has been replaced with `additional_properties`.
+- The value of the `enum` attribute is now always an Array. If it has only one value, it will be a one-element Array.
+
+### Upgrading to >= 1.4.0
+
+- Official support for ruby < 2.5 removed, ruby 2.5 only in testing mode, but no support.
+
+### Upgrading to >= 1.3.0
+
+- The model (entity) description no longer comes from the route description. It will have a default value: `<<EntityName>> model`.
+
+### Upgrading to >= 1.2.0
+
+- The entity_name class method is now called on parent classes for inherited entities. Now you can do this
+
+```ruby
+module Some::Long::Module
+  class Base < Grape::Entity
+    # ... other shared logic
+    def self.entity_name
+      "V2::#{self.to_s.demodulize}"
+    end
+  end
+
+  def MyEntity < Base
+    # ....
+  end
+
+  def OtherEntity < Base
+    # revert back to the default behavior by hiding the method
+    private_class_method :entity_name
+  end
+end
+```
+
+- Full class name is modified to use `_` separator (e.g. `A_B_C` instead of `A::B::C`).
+
+### Upgrading to >= 1.1.0
+
+Full class name is used for referencing entity by default (e.g. `A::B::C` instead of just `C`). `Entity` and `Entities` suffixes and prefixes are omitted (e.g. if entity name is `Entities::SomeScope::MyFavourite::Entity` only `SomeScope::MyFavourite` will be used).
+
+### Upgrading to >= 0.26.1
+
+The format can now be specified,
+to achieve it for definition properties one have to use grape-swagger-entity >= 0.1.6.
+
+Usage of option `markdown` won't no longer be supported,
+cause OAPI accepts [GFM](https://help.github.com/articles/github-flavored-markdown) and plain text.
+(see: [description of `Info`](https://github.com/OAI/OpenAPI-Specification/blob/OpenAPI.next/versions/2.0.md#info-object))
+
+### Upgrading to >= 0.25.2
+
+Avoids ambiguous documentation of array parameters,
+by enforcing correct usage of both possibilities:
+
+1. Array of primitive types
+  ```ruby
+  params do
+    requires :foo, type: Array[String]
+  end
+  ```
+
+2. Array of objects
+  ```ruby
+  params do
+    requires :put_params, type: Array do
+      requires :op, type: String
+      requires :path, type: String
+      requires :value, type: String
+    end
+  end
+```
+
+### Upgrading to >= 0.25.0
+
+The global tag set now only includes tags for documented routes. This behaviour has impact in particular for calling the documtation of a specific route.
+
+### Upgrading to >= 0.21.0
+
+With grape >= 0.21.0, `grape-entity` support moved to separate gem `grape-swagger-entity`, if you use grape entity, update your Gemfile:
+
+```ruby
+gem 'grape-swagger'
+gem 'grape-swagger-entity'
+```
+
+`add_swagger_documentation` has changed from
+``` ruby
+  add_swagger_documentation \
+    api_version: '0.0.1'
+```
+to
+
+``` ruby
+  add_swagger_documentation \
+    doc_version: '0.0.1'
+```
+
+The API version self, would be set by grape, see -> [spec for #403](https://github.com/ruby-grape/grape-swagger/blob/master/spec/issues/403_versions_spec.rb).
+
+
+
+### Upgrading to >= 0.10.2
+
+With grape >= 0.12.0, support for `notes` is replaced by passing a block `detail` option specified. For future compatibility, update your code:
+
+```ruby
+desc 'Get all kittens!', notes: 'this will expose all the kittens'
+```
+
+to
+
+``` ruby
+ desc 'Get all kittens!' do
+  detail 'this will expose all the kittens'
+end
+```
+Be aware of https://github.com/ruby-grape/grape/issues/920, currently grape accepts either an option hash OR a block for `desc`.
+
+### Upgrading to >= 0.9.0
+
+#### Grape-Swagger-Rails
+
+If you're using [grape-swagger-rails](https://github.com/ruby-grape/grape-swagger-rails), remove the `.json` extension from `GrapeSwaggerRails.options.url`.
+
+For example, change
+
+```ruby
+GrapeSwaggerRails.options.url = '/api/v1/swagger_doc.json'
+```
+
+to
+
+```ruby
+GrapeSwaggerRails.options.url = '/api/v1/swagger_doc'
+```
+
+See [#187](https://github.com/ruby-grape/grape-swagger/issues/187) for more information.
+
+#### Grape 0.10.0
+
+If your API uses Grape 0.10.0 or newer with a single `format :json` directive, add `hide_format: true` to `add_swagger_documentation`. Otherwise nested routes will render with `.json` links to your API documentation, which will fail with a 404 Not Found.
+
+### Upgrading to >= 0.8.0
+
+#### Changes in Configuration
+
+The following options have been added, removed or have been changed in the grape-swagger interface:
+
+* `markdown: true/false` => `markdown: GrapeSwagger::Markdown::KramdownAdapter`
+
+#### Markdown
+
+You can now configure a markdown adapter. This was originally changed because of performance issues with Kramdown and the `markdown` option no longer takes a boolean argument. Built-in adapters include Kramdown and Redcarpet.
+
+##### Kramdown
+
+To configure the markdown with Kramdown, add the kramdown gem to your Gemfile:
+
+`gem 'kramdown'`
+
+Configure grape-swagger as follows:
+
+```ruby
+add_swagger_documentation (
+    markdown: GrapeSwagger::Markdown::KramdownAdapter
+)
+```
+
+#### Redcarpet
+
+To configure markdown with Redcarpet, add the redcarpet and the rouge gem to your Gemfile. Note that Redcarpet does not work with JRuby.
+
+```ruby
+gem 'redcarpet'
+gem 'rouge'
+```
+
+Configure grape-swagger as follows:
+
+```ruby
+add_swagger_documentation (
+    markdown: GrapeSwagger::Markdown::RedcarpetAdapter
+)
+```
+
+See [#142](https://github.com/ruby-grape/grape-swagger/pull/142) and documentation section [Markdown in Notes](https://github.com/ruby-grape/grape-swagger#markdown-in-notes) for more information.

data/example/api/endpoints.rb

@@ -0,0 +1,131 @@
+require 'grape-entity'
+require './api/entities'
+
+module Api
+  class Spline
+    attr_accessor :id, :x, :y, :reticulated
+  end
+
+  module Endpoints
+    class Root < Grape::API
+      desc 'API Root'
+      get do
+        {
+          splines_url: '/splines',
+          file_url: '/file'
+        }
+      end
+    end
+
+    class Splines < Grape::API
+      @@splines = []
+
+      namespace :splines do
+        #
+        desc 'Get all splines',
+          is_array: true,
+          http_codes: [
+            { code: 200, message: 'get Splines', model: Api::Entities::Splines },
+            { code: 422, message: 'SplinesOutError' }
+          ]
+        get do
+          present :items, @@splines, with: Entities::Splines
+        end
+
+        #
+        desc 'Return a spline.',
+          http_codes: [
+            { code: 200, message: 'get Splines' },
+            { code: 422, message: 'SplinesOutError' }
+          ]
+        params do
+          requires :id, type: Integer, desc: 'Spline id.'
+        end
+        get ':id' do
+          error!(code: 422, message: 'SplinesOutError') unless @@splines[params[:id] - 1]
+
+          present @@splines[params[:id] - 1], with: Entities::Splines
+        end
+
+        #
+        desc 'Create a spline.',
+          http_codes: [
+            { code: 201, message: 'Spline created', model: Api::Entities::Splines }
+          ]
+        params do
+          requires :spline, type: Hash do
+            requires :x, type: Numeric
+            requires :y, type: Numeric
+          end
+          optional :reticulated, type: Boolean, default: true, desc: 'True if the spline is reticulated.'
+        end
+        post do
+          spline = Spline.new
+          spline.id = @@splines.size + 1
+          spline.x =  (params[:spline][:x] / params[:spline][:y] || 0.0)
+          spline.y =  (params[:spline][:y] / params[:spline][:x] || 0.0)
+          spline.reticulated =  params[:reticulated]
+
+          @@splines << spline
+
+          present spline, with: Entities::Splines
+        end
+
+        #
+        desc 'Update a spline.',
+          http_codes: [
+            { code: 200, message: 'update Splines', model: Api::Entities::Splines },
+            { code: 422, message: 'SplinesOutError' }
+          ]
+        params do
+          requires :id, type: Integer, desc: 'Spline id.'
+          optional :spline, type: Hash do
+            optional :x, type: Numeric
+            optional :y, type: Numeric
+          end
+          optional :reticulated, type: Boolean, default: true, desc: 'True if the spline is reticulated.'
+        end
+        put ':id' do
+          error!(code: 422, message: 'SplinesOutError') unless @@splines[params[:id] - 1]
+
+          update_data = params[:spline]
+          spline      = @@splines[params[:id] - 1]
+
+          spline.reticulated = !!update_data[:reticulated]
+          spline.x           = update_data[:x] / update_data[:y] || 0.0
+          spline.y           = update_data[:y] / update_data[:x] || 0.0
+
+          present spline, with: Entities::Splines
+        end
+
+        #
+        desc 'Delete a spline.'
+        params do
+          requires :id, type: Integer, desc: 'Spline id.'
+        end
+        delete ':id' do
+          error!(code: 422, message: 'SplinesOutError') unless @@splines[params[:id] - 1]
+
+          @@splines.delete_at(params[:id] - 1)
+          { 'deleted' => params[:id] }
+        end
+      end
+    end
+
+    class FileAccessor < Grape::API
+      namespace :file do
+        desc 'Update image',
+             details: "# TEST api for testing uploading\n
+                       # curl --form file=@splines.png http://localhost:9292/file/upload",
+             content_type: 'application/octet-stream'
+        post 'upload' do
+          filename = params[:file][:filename]
+          content_type 'binary', 'application/octet-stream'
+          # env['api.format'] = :binary # there's no formatter for :binary, data will be returned "as is"
+          header 'Content-Disposition', "attachment; filename*=UTF-8''#{URI.escape(filename)}"
+          params[:file][:tempfile].read
+        end
+      end
+    end
+  end
+end

data/example/api/entities.rb

@@ -0,0 +1,18 @@
+require 'grape-entity'
+
+module Api
+  module Entities
+    class Splines < Grape::Entity
+      expose :id, documentation: { type: Integer, desc: 'identity of a resource' }
+      expose :x, documentation: { type: Float, desc: 'x-value' }
+      expose :y, documentation: { type: Float, desc: 'y-value' }
+      expose :path, documentation: { type: String, desc: 'the requested resource' }
+
+      private
+
+      def path
+        "/#{object.class.name.demodulize.to_s.underscore}/#{object.id}"
+      end
+    end
+  end
+end

data/example/config.ru

@@ -0,0 +1,42 @@
+Bundler.require ENV['RACK_ENV']
+
+use Rack::Cors do
+  allow do
+    origins '*'
+    resource '*', headers: :any, methods: [:get, :post, :put, :delete, :options]
+  end
+end
+
+require 'grape'
+
+require './api/endpoints'
+require './api/entities'
+
+class Base < Grape::API
+  require '../lib/grape-swagger'
+  format :json
+
+  mount Api::Endpoints::Root
+  mount Api::Endpoints::Splines
+  mount Api::Endpoints::FileAccessor
+
+  before do
+    header['Access-Control-Allow-Origin'] = '*'
+    header['Access-Control-Request-Method'] = '*'
+  end
+
+  # global exception handler, used for error notifications
+  rescue_from :all do |e|
+    raise e
+    error_response(message: "Internal server error: #{e}", status: 500)
+  end
+
+  add_swagger_documentation hide_documentation_path: true,
+                            api_version: 'v1',
+                            info: {
+                              title: 'Horses and Hussars',
+                              description: 'Demo app for dev of grape swagger 2.0'
+                            }
+end
+
+run Base.new

data/example/example_requests.postman_collection

@@ -0,0 +1,146 @@
+{
+	"id": "1a2c4a65-9c99-3435-17db-307763b28fd1",
+	"name": "grape-rackup",
+	"description": "",
+	"order": [
+		"cf633582-c2ea-cb44-24d7-d64e73a65049",
+		"60bd637b-7b77-b280-d4f7-3d3d38cd86ef",
+		"4780e2ef-f05d-f464-9d18-538c5960be3c",
+		"f83c2241-c239-13ea-bffb-255436e95863",
+		"0648649b-9e54-1bc5-f835-2c690f67d47a"
+	],
+	"folders": [],
+	"timestamp": 1453407636651,
+	"owner": "",
+	"remoteLink": "",
+	"public": false,
+	"requests": [
+		{
+			"id": "0648649b-9e54-1bc5-f835-2c690f67d47a",
+			"headers": "Content-Type: application/json\n",
+			"url": "http://localhost:9292/splines/1",
+			"preRequestScript": "",
+			"pathVariables": {},
+			"method": "DELETE",
+			"data": [],
+			"dataMode": "params",
+			"version": 2,
+			"tests": "",
+			"currentHelper": "normal",
+			"helperAttributes": {},
+			"time": 1453408596777,
+			"name": "http://localhost:9292/splines",
+			"description": "",
+			"collectionId": "1a2c4a65-9c99-3435-17db-307763b28fd1",
+			"responses": []
+		},
+		{
+			"id": "4780e2ef-f05d-f464-9d18-538c5960be3c",
+			"headers": "Content-Type: application/json\n",
+			"url": "http://localhost:9292/splines/1",
+			"pathVariables": {},
+			"preRequestScript": "",
+			"method": "GET",
+			"collectionId": "1a2c4a65-9c99-3435-17db-307763b28fd1",
+			"data": [
+				{
+					"key": "required_group[required_param_1]",
+					"value": "sadf",
+					"type": "text",
+					"enabled": true
+				},
+				{
+					"key": "required_group[required_param_2]",
+					"value": "fgsd",
+					"type": "text",
+					"enabled": true
+				}
+			],
+			"dataMode": "params",
+			"name": "http://localhost:9292/splines",
+			"description": "",
+			"descriptionFormat": "html",
+			"time": 1453408415061,
+			"version": 2,
+			"responses": [],
+			"tests": "",
+			"currentHelper": "normal",
+			"helperAttributes": {}
+		},
+		{
+			"id": "60bd637b-7b77-b280-d4f7-3d3d38cd86ef",
+			"headers": "Content-Type: application/json\n",
+			"url": "http://localhost:9292/splines",
+			"pathVariables": {},
+			"preRequestScript": "",
+			"method": "GET",
+			"collectionId": "1a2c4a65-9c99-3435-17db-307763b28fd1",
+			"data": [
+				{
+					"key": "required_group[required_param_1]",
+					"value": "sadf",
+					"type": "text",
+					"enabled": true
+				},
+				{
+					"key": "required_group[required_param_2]",
+					"value": "fgsd",
+					"type": "text",
+					"enabled": true
+				}
+			],
+			"dataMode": "params",
+			"name": "http://localhost:9292/splines",
+			"description": "",
+			"descriptionFormat": "html",
+			"time": 1453408387712,
+			"version": 2,
+			"responses": [],
+			"tests": "",
+			"currentHelper": "normal",
+			"helperAttributes": {}
+		},
+		{
+			"id": "cf633582-c2ea-cb44-24d7-d64e73a65049",
+			"headers": "Content-Type: application/json\n",
+			"url": "http://localhost:9292/splines",
+			"pathVariables": {},
+			"preRequestScript": "",
+			"method": "POST",
+			"collectionId": "1a2c4a65-9c99-3435-17db-307763b28fd1",
+			"data": [],
+			"dataMode": "raw",
+			"name": "http://localhost:9292/splines",
+			"description": "",
+			"descriptionFormat": "html",
+			"time": 1453407769825,
+			"version": 2,
+			"responses": [],
+			"tests": "",
+			"currentHelper": "normal",
+			"helperAttributes": {},
+			"rawModeData": "{\n    \"spline\":{\n        \"x\":1.23,\n        \"y\":3.14\n    }\n}"
+		},
+		{
+			"id": "f83c2241-c239-13ea-bffb-255436e95863",
+			"headers": "Content-Type: application/json\n",
+			"url": "http://localhost:9292/splines/1",
+			"pathVariables": {},
+			"preRequestScript": "",
+			"method": "PUT",
+			"collectionId": "1a2c4a65-9c99-3435-17db-307763b28fd1",
+			"data": [],
+			"dataMode": "raw",
+			"name": "http://localhost:9292/splines",
+			"description": "",
+			"descriptionFormat": "html",
+			"time": 1453408494448,
+			"version": 2,
+			"responses": [],
+			"tests": "",
+			"currentHelper": "normal",
+			"helperAttributes": {},
+			"rawModeData": "{\n    \"spline\":{\n        \"x\":131.23,\n        \"y\":93.14\n    }\n}"
+		}
+	]
+}

data/grape-swagger.gemspec

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+$LOAD_PATH.push File.expand_path('lib', __dir__)
+require 'grape-swagger/version'
+
+Gem::Specification.new do |s|
+  s.name        = 'gitlab-grape-swagger'
+  s.version     = GrapeSwagger::VERSION
+  s.platform    = Gem::Platform::RUBY
+  s.authors     = ['LeFnord', 'Tim Vandecasteele']
+  s.email       = ['pscholz.le@gmail.com', 'tim.vandecasteele@gmail.com']
+  s.homepage    = 'https://gitlab.com/gitlab-org/ruby/gems/grape-swagger'
+  s.summary     = 'Add auto generated documentation to your Grape API that can be displayed with Swagger.'
+  s.license     = 'MIT'
+
+  s.metadata['rubygems_mfa_required'] = 'true'
+
+  s.required_ruby_version = '>= 2.7'
+  s.add_runtime_dependency 'grape', '~> 1.3'
+
+  s.files         = `git ls-files`.split("\n")
+  s.require_paths = ['lib']
+end