swagger-blocks 0.0.1 → 1.0.0

Sign up to get free protection for your applications and to get access to all the features.
checksums.yaml CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  SHA1:
3
- metadata.gz: b309bb304d3b80b0a6e213b7f3ec59ae1c9fa51a
4
- data.tar.gz: c68fce426638012787fc21ea5f6ee4c514ae4d18
3
+ metadata.gz: 1feb49d6ff4f98fa20993ea31858e263c5ce09a4
4
+ data.tar.gz: 202eb893193d3bad7599791c72014d0f06a0a045
5
5
  SHA512:
6
- metadata.gz: f4d95e4aedf7c8107d2c09e4c814cdc59c7336e5fb4370e345055fc01de0b7807787d74ca9f6250d4a5f7d6182adb3f7ef0252fe598171c7332d0dfa9490828c
7
- data.tar.gz: f419056f5dd26c88d8dafd5f1fcbff859015257897db939ff1d46e13f97e481020362c2db6c948b35a8c80f3a9deb7d6bc21212d262fcdde88c546f5df6e9d10
6
+ metadata.gz: b11d4343fa07338eb7706960b9aa0e1e2714b4abd46948d894e42a7ff2deb93bfbc9b6d38db61896d4d3bebccda52995b85f71a8ec23c4502d0c2297f41e1f68
7
+ data.tar.gz: 83bc75e151706a81535523a9a7b797c45943324a50ee913ed35c62f2453ddf8d8beaaf950c7ab5a1c9d8f1b1557a5885de2094ae5c9609bb9f6d16064c00ea2e
data/README.md CHANGED
@@ -2,25 +2,171 @@
2
2
 
3
3
  [![Build Status](https://travis-ci.org/fotinakis/swagger-blocks.svg?branch=master)](https://travis-ci.org/fotinakis/swagger-blocks)
4
4
 
5
- TODO: Write a gem description
5
+ Swagger::Blocks is a DSL for pure Ruby code blocks that can be turned into JSON.
6
+
7
+ It helps you write API docs in the [Swagger](https://helloreverb.com/developers/swagger) style in Ruby and then automatically build JSON that is compatible with [Swagger UI](http://petstore.swagger.wordnik.com/#!/pet).
8
+
9
+ ## Features
10
+
11
+ * Supports **live updating** by design. Change code, refresh your API docs.
12
+ * **Works with all Ruby web frameworks** including Rails, Sinatra, etc.
13
+ * **100% support** for all features of the [Swagger 1.2 spec](https://github.com/wordnik/swagger-spec/blob/master/versions/1.2.md).
14
+ * Flexible—you can use Swagger::Blocks anywhere, split up blocks to fit your style preferences, etc. Since it's pure Ruby and serves definitions dynamically, you can easily use initializers/config objects to change values or even show/hide different APIs based on environment.
15
+ * 1:1 naming with the Swagger spec—block names and nesting should match almost exactly with the swagger spec, with rare exceptions to make things more convenient.
6
16
 
7
17
  ## Installation
8
18
 
9
19
  Add this line to your application's Gemfile:
10
20
 
11
21
  gem 'swagger-blocks'
22
+
23
+ Or install directly with `gem install swagger-blocks`. **Requires Ruby 2.1+**
24
+
25
+ ## Example (Rails)
26
+
27
+ This is a simplified example based on the objects in the Petstore [Swagger Sample App](http://petstore.swagger.wordnik.com/#!/pet). For a more complex and complete example, see the [swagger_blocks_spec.rb](https://github.com/fotinakis/swagger-blocks/blob/master/spec/lib/swagger_blocks_spec.rb) file.
28
+
29
+ Also note that Rails is not required, you can use Swagger::Blocks with any Ruby web framework.
30
+
31
+ #### PetsController
32
+
33
+ Parameters and features below are defined by the [Swagger 1.2 spec](https://github.com/wordnik/swagger-spec/blob/master/versions/1.2.md).
34
+
35
+ ```Ruby
36
+ class PetsController < ActionController::Base
37
+ include Swagger::Blocks
38
+
39
+ swagger_api_root :pets do
40
+ key :swaggerVersion, '1.2'
41
+ key :apiVersion, '1.0.0'
42
+ key :basePath, 'http://petstore.swagger.wordnik.com/api'
43
+ key :resourcePath, '/pets'
44
+ api do
45
+ key :path, '/pets/{petId}'
46
+ operation do
47
+ key :method, 'GET'
48
+ key :summary, 'Find pet by ID'
49
+ key :notes, 'Returns a pet based on ID'
50
+ key :type, :Pet
51
+ key :nickname, :getPetById
52
+ parameter do
53
+ key :paramType, :path
54
+ key :name, :petId
55
+ key :description, 'ID of pet that needs to be fetched'
56
+ key :required, true
57
+ key :type, :integer
58
+ end
59
+ response_message do
60
+ key :code, 400
61
+ key :message, 'Invalid ID supplied'
62
+ end
63
+ response_message do
64
+ key :code, 404
65
+ key :message, 'Pet not found'
66
+ end
67
+ end
68
+ end
69
+ end
70
+
71
+ # ...
72
+ end
73
+ ```
74
+
75
+ #### Pet model
76
+
77
+ ```Ruby
78
+ class Pet < ActiveRecord::Base
79
+ include Swagger::Blocks
12
80
 
13
- And then execute:
81
+ swagger_model :Pet do
82
+ key :id, :Pet
83
+ key :required, [:id, :name]
84
+ property :id do
85
+ key :type, :integer
86
+ key :format, :int64
87
+ key :description, 'unique identifier for the pet'
88
+ key :minimum, '0.0'
89
+ key :maximum, '100.0'
90
+ end
91
+ property :name do
92
+ key :type, :string
93
+ end
94
+ property :photoUrls do
95
+ key :type, :array
96
+ items do
97
+ key :type, :string
98
+ end
99
+ end
100
+ property :status do
101
+ key :type, :string
102
+ key :description, 'pet status in the store'
103
+ key :enum, [:available, :pending, :sold]
104
+ end
105
+ end
106
+
107
+ # ...
108
+ end
109
+ ```
14
110
 
15
- $ bundle
111
+ #### Docs controller
16
112
 
17
- Or install it yourself as:
113
+ To integrate these definitions with Swagger UI, we need a docs controller that can serve the JSON definitions.
18
114
 
19
- $ gem install swagger-blocks
115
+ ```Ruby
116
+ resources :apidocs, only: [:index, :show]
117
+ ```
20
118
 
21
- ## Usage
119
+ ```Ruby
120
+ class ApidocsController < ActionController::Base
121
+ include Swagger::Blocks
22
122
 
23
- TODO: Write usage instructions here
123
+ swagger_root do
124
+ key :swaggerVersion, '1.2'
125
+ key :apiVersion, '1.0.0'
126
+ info do
127
+ key :title, 'Swagger Sample App'
128
+ end
129
+ api do
130
+ key :path, '/pets'
131
+ key :description, 'Operations about pets'
132
+ end
133
+ end
134
+
135
+ # A list of all classes that have swagger_* declarations.
136
+ SWAGGERED_CLASSES = [
137
+ PetsController,
138
+ Pets,
139
+ self,
140
+ ].freeze
141
+
142
+ def index
143
+ render json: Swagger::Blocks.build_root_json(SWAGGERED_CLASSES)
144
+ end
145
+
146
+ def show
147
+ render json: Swagger::Blocks.build_api_json(params[:id], SWAGGERED_CLASSES)
148
+ end
149
+ end
150
+
151
+ ```
152
+
153
+ The special part of this controller are these lines:
154
+
155
+ ```Ruby
156
+ render json: Swagger::Blocks.build_root_json(SWAGGERED_CLASSES)
157
+ ```
158
+
159
+ ```Ruby
160
+ render json: Swagger::Blocks.build_api_json(params[:id], SWAGGERED_CLASSES)
161
+ ```
162
+
163
+ Those are the only lines necessary to build the root Swagger [Resource Listing](https://github.com/wordnik/swagger-spec/blob/master/versions/1.2.md#51-resource-listing) JSON and the JSON for each Swagger [API Declaration](https://github.com/wordnik/swagger-spec/blob/master/versions/1.2.md#52-api-declaration). You simply pass in a list of all the "swaggered" classes in your app.
164
+
165
+ Now, simply point Swagger UI at `/apidocs` and everything should Just Work™. If you change any of the Swagger block definitions, you can simply refresh Swagger UI to see the changes.
166
+
167
+ ## Reference
168
+
169
+ See the [swagger_blocks_spec.rb](https://github.com/fotinakis/swagger-blocks/blob/master/spec/lib/swagger_blocks_spec.rb) for examples of more complex features and declarations possible.
24
170
 
25
171
  ## Contributing
26
172
 
@@ -29,3 +175,7 @@ TODO: Write usage instructions here
29
175
  3. Commit your changes (`git commit -am 'Add some feature'`)
30
176
  4. Push to the branch (`git push origin my-new-feature`)
31
177
  5. Create a new Pull Request
178
+
179
+ ## Credits
180
+
181
+ Original idea inspired by **[@richhollis](https://github.com/richhollis/)**'s [swagger-docs](https://github.com/richhollis/swagger-docs/) gem.
@@ -1,5 +1,5 @@
1
1
  module Swagger
2
2
  module Blocks
3
- VERSION = '0.0.1'
3
+ VERSION = '1.0.0'
4
4
  end
5
5
  end
@@ -8,7 +8,7 @@ Gem::Specification.new do |spec|
8
8
  spec.version = Swagger::Blocks::VERSION
9
9
  spec.authors = ['Mike Fotinakis']
10
10
  spec.email = ['mike@fotinakis.com']
11
- spec.summary = %q{Define and generate Swagger JSON files in Ruby.}
11
+ spec.summary = %q{Define and serve live-updating Swagger JSON for Ruby apps.}
12
12
  spec.description = %q{}
13
13
  spec.homepage = 'https://github.com/fotinakis/swagger-blocks'
14
14
  spec.license = 'MIT'
@@ -17,6 +17,7 @@ Gem::Specification.new do |spec|
17
17
  spec.executables = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
18
18
  spec.test_files = spec.files.grep(%r{^(test|spec|features)/})
19
19
  spec.require_paths = ['lib']
20
+ spec.required_ruby_version = '>= 2.1'
20
21
 
21
22
  spec.add_development_dependency 'bundler'
22
23
  spec.add_development_dependency 'rake'
metadata CHANGED
@@ -1,14 +1,14 @@
1
1
  --- !ruby/object:Gem::Specification
2
2
  name: swagger-blocks
3
3
  version: !ruby/object:Gem::Version
4
- version: 0.0.1
4
+ version: 1.0.0
5
5
  platform: ruby
6
6
  authors:
7
7
  - Mike Fotinakis
8
8
  autorequire:
9
9
  bindir: bin
10
10
  cert_chain: []
11
- date: 2014-09-07 00:00:00.000000000 Z
11
+ date: 2015-01-20 00:00:00.000000000 Z
12
12
  dependencies:
13
13
  - !ruby/object:Gem::Dependency
14
14
  name: bundler
@@ -99,7 +99,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
99
99
  requirements:
100
100
  - - ">="
101
101
  - !ruby/object:Gem::Version
102
- version: '0'
102
+ version: '2.1'
103
103
  required_rubygems_version: !ruby/object:Gem::Requirement
104
104
  requirements:
105
105
  - - ">="
@@ -107,10 +107,10 @@ required_rubygems_version: !ruby/object:Gem::Requirement
107
107
  version: '0'
108
108
  requirements: []
109
109
  rubyforge_project:
110
- rubygems_version: 2.4.1
110
+ rubygems_version: 2.2.2
111
111
  signing_key:
112
112
  specification_version: 4
113
- summary: Define and generate Swagger JSON files in Ruby.
113
+ summary: Define and serve live-updating Swagger JSON for Ruby apps.
114
114
  test_files:
115
115
  - spec/lib/swagger_api_declaration.json
116
116
  - spec/lib/swagger_blocks_spec.rb