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 +4 -4
- data/README.md +157 -7
- data/lib/swagger/blocks/version.rb +1 -1
- data/swagger-blocks.gemspec +2 -1
- metadata +5 -5
checksums.yaml
CHANGED
@@ -1,7 +1,7 @@
|
|
1
1
|
---
|
2
2
|
SHA1:
|
3
|
-
metadata.gz:
|
4
|
-
data.tar.gz:
|
3
|
+
metadata.gz: 1feb49d6ff4f98fa20993ea31858e263c5ce09a4
|
4
|
+
data.tar.gz: 202eb893193d3bad7599791c72014d0f06a0a045
|
5
5
|
SHA512:
|
6
|
-
metadata.gz:
|
7
|
-
data.tar.gz:
|
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
|
-
|
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
|
-
|
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
|
-
|
111
|
+
#### Docs controller
|
16
112
|
|
17
|
-
|
113
|
+
To integrate these definitions with Swagger UI, we need a docs controller that can serve the JSON definitions.
|
18
114
|
|
19
|
-
|
115
|
+
```Ruby
|
116
|
+
resources :apidocs, only: [:index, :show]
|
117
|
+
```
|
20
118
|
|
21
|
-
|
119
|
+
```Ruby
|
120
|
+
class ApidocsController < ActionController::Base
|
121
|
+
include Swagger::Blocks
|
22
122
|
|
23
|
-
|
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.
|
data/swagger-blocks.gemspec
CHANGED
@@ -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
|
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
|
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:
|
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: '
|
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.
|
110
|
+
rubygems_version: 2.2.2
|
111
111
|
signing_key:
|
112
112
|
specification_version: 4
|
113
|
-
summary: Define and
|
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
|