swagger-blocks 1.4.0 → 2.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (36) hide show
  1. checksums.yaml +4 -4
  2. data/README.md +7 -6
  3. data/lib/swagger/blocks.rb +28 -775
  4. data/lib/swagger/blocks/class_methods.rb +65 -0
  5. data/lib/swagger/blocks/errors.rb +8 -0
  6. data/lib/swagger/blocks/internal_helpers.rb +52 -0
  7. data/lib/swagger/blocks/node.rb +64 -0
  8. data/lib/swagger/blocks/nodes/all_of_node.rb +42 -0
  9. data/lib/swagger/blocks/nodes/contact_node.rb +9 -0
  10. data/lib/swagger/blocks/nodes/example_node.rb +9 -0
  11. data/lib/swagger/blocks/nodes/external_docs_node.rb +9 -0
  12. data/lib/swagger/blocks/nodes/header_node.rb +12 -0
  13. data/lib/swagger/blocks/nodes/info_node.rb +16 -0
  14. data/lib/swagger/blocks/nodes/items_node.rb +14 -0
  15. data/lib/swagger/blocks/nodes/license_node.rb +9 -0
  16. data/lib/swagger/blocks/nodes/operation_node.rb +30 -0
  17. data/lib/swagger/blocks/nodes/parameter_node.rb +16 -0
  18. data/lib/swagger/blocks/nodes/path_node.rb +24 -0
  19. data/lib/swagger/blocks/nodes/properties_node.rb +11 -0
  20. data/lib/swagger/blocks/nodes/property_node.rb +17 -0
  21. data/lib/swagger/blocks/nodes/response_node.rb +24 -0
  22. data/lib/swagger/blocks/nodes/root_node.rb +53 -0
  23. data/lib/swagger/blocks/nodes/schema_node.rb +30 -0
  24. data/lib/swagger/blocks/nodes/scopes_node.rb +9 -0
  25. data/lib/swagger/blocks/nodes/security_requirement_node.rb +9 -0
  26. data/lib/swagger/blocks/nodes/security_scheme_node.rb +14 -0
  27. data/lib/swagger/blocks/nodes/tag_node.rb +15 -0
  28. data/lib/swagger/blocks/nodes/xml_node.rb +9 -0
  29. data/lib/swagger/blocks/root.rb +25 -0
  30. data/lib/swagger/blocks/version.rb +1 -1
  31. data/spec/lib/swagger_v2_blocks_spec.rb +0 -5
  32. metadata +28 -9
  33. data/README_v1_2.md +0 -143
  34. data/spec/lib/swagger_api_declaration.json +0 -201
  35. data/spec/lib/swagger_blocks_spec.rb +0 -349
  36. data/spec/lib/swagger_resource_listing.json +0 -60
@@ -0,0 +1,53 @@
1
+ module Swagger
2
+ module Blocks
3
+ module Nodes
4
+ class RootNode < Node
5
+
6
+ def info(inline_keys = nil, &block)
7
+ self.data[:info] = Swagger::Blocks::Nodes::InfoNode.call(version: version, inline_keys: inline_keys, &block)
8
+ end
9
+
10
+ def parameter(param, inline_keys = nil, &block)
11
+ raise NotSupportedError unless is_swagger_2_0?
12
+
13
+ # TODO validate 'param' is as per spec
14
+ self.data[:parameters] ||= {}
15
+ self.data[:parameters][param] = Swagger::Blocks::Nodes::ParameterNode.call(version: version, inline_keys: inline_keys, &block)
16
+ end
17
+
18
+ def response(resp, inline_keys = nil, &block)
19
+ raise NotSupportedError unless is_swagger_2_0?
20
+
21
+ # TODO validate 'resp' is as per spec
22
+ self.data[:responses] ||= {}
23
+ self.data[:responses][resp] = Swagger::Blocks::Nodes::ResponseNode.call(version: version, inline_keys: inline_keys, &block)
24
+ end
25
+
26
+ def security_definition(name, inline_keys = nil, &block)
27
+ raise NotSupportedError unless is_swagger_2_0?
28
+
29
+ self.data[:securityDefinitions] ||= {}
30
+ self.data[:securityDefinitions][name] = Swagger::Blocks::Nodes::SecuritySchemeNode.call(version: version, inline_keys: inline_keys, &block)
31
+ end
32
+
33
+ def security(inline_keys = nil, &block)
34
+ raise NotSupportedError unless is_swagger_2_0?
35
+
36
+ self.data[:security] ||= []
37
+ self.data[:security] << Swagger::Blocks::Nodes::SecurityRequirementNode.call(version: version, inline_keys: inline_keys, &block)
38
+ end
39
+
40
+ def tag(inline_keys = nil, &block)
41
+ raise NotSupportedError unless is_swagger_2_0?
42
+
43
+ self.data[:tags] ||= []
44
+ self.data[:tags] << Swagger::Blocks::Nodes::TagNode.call(version: version, inline_keys: inline_keys, &block)
45
+ end
46
+
47
+ # Use 'tag' instead.
48
+ # @deprecated
49
+ alias_method :tags, :tag
50
+ end
51
+ end
52
+ end
53
+ end
@@ -0,0 +1,30 @@
1
+ module Swagger
2
+ module Blocks
3
+ module Nodes
4
+ # v2.0: https://github.com/swagger-api/swagger-spec/blob/master/versions/2.0.md#schema-object
5
+ class SchemaNode < Node
6
+ def items(inline_keys = nil, &block)
7
+ self.data[:items] = Swagger::Blocks::Nodes::ItemsNode.call(version: version, inline_keys: inline_keys, &block)
8
+ end
9
+
10
+ def allOf(&block)
11
+ self.data[:allOf] = Swagger::Blocks::Nodes::AllOfNode.call(version: version, &block)
12
+ end
13
+
14
+ def property(name, inline_keys = nil, &block)
15
+ self.data[:properties] ||= Swagger::Blocks::Nodes::PropertiesNode.new
16
+ self.data[:properties].version = version
17
+ self.data[:properties].property(name, inline_keys, &block)
18
+ end
19
+
20
+ def xml(inline_keys = nil, &block)
21
+ self.data[:xml] = Swagger::Blocks::Nodes::XmlNode.call(version: version, inline_keys: inline_keys, &block)
22
+ end
23
+
24
+ def externalDocs(inline_keys = nil, &block)
25
+ self.data[:externalDocs] = Swagger::Blocks::Nodes::ExternalDocsNode.call(version: version, inline_keys: inline_keys, &block)
26
+ end
27
+ end
28
+ end
29
+ end
30
+ end
@@ -0,0 +1,9 @@
1
+ module Swagger
2
+ module Blocks
3
+ module Nodes
4
+ # v2.0: https://github.com/swagger-api/swagger-spec/blob/master/versions/2.0.md#scopes-object
5
+ class ScopesNode < Node
6
+ end
7
+ end
8
+ end
9
+ end
@@ -0,0 +1,9 @@
1
+ module Swagger
2
+ module Blocks
3
+ module Nodes
4
+ # v2.0: https://github.com/swagger-api/swagger-spec/blob/master/versions/2.0.md#securityRequirementObject
5
+ class SecurityRequirementNode < Node
6
+ end
7
+ end
8
+ end
9
+ end
@@ -0,0 +1,14 @@
1
+ module Swagger
2
+ module Blocks
3
+ module Nodes
4
+ # v2.0: https://github.com/swagger-api/swagger-spec/blob/master/versions/2.0.md#security-scheme-object
5
+ class SecuritySchemeNode < Node
6
+ # TODO support ^x- Vendor Extensions
7
+
8
+ def scopes(inline_keys = nil, &block)
9
+ self.data[:scopes] = Swagger::Blocks::Nodes::ScopesNode.call(version: version, inline_keys: inline_keys, &block)
10
+ end
11
+ end
12
+ end
13
+ end
14
+ end
@@ -0,0 +1,15 @@
1
+ module Swagger
2
+ module Blocks
3
+ module Nodes
4
+ # v2.0: https://github.com/swagger-api/swagger-spec/blob/master/versions/2.0.md#tag-object
5
+ class TagNode < Node
6
+
7
+ # TODO support ^x- Vendor Extensions
8
+
9
+ def externalDocs(inline_keys = nil, &block)
10
+ self.data[:externalDocs] = Swagger::Blocks::Nodes::ExternalDocsNode.call(version: version, inline_keys: inline_keys, &block)
11
+ end
12
+ end
13
+ end
14
+ end
15
+ end
@@ -0,0 +1,9 @@
1
+ module Swagger
2
+ module Blocks
3
+ module Nodes
4
+ # v2.0:
5
+ class XmlNode < Node
6
+ end
7
+ end
8
+ end
9
+ end
@@ -0,0 +1,25 @@
1
+ require 'json'
2
+ require 'swagger/blocks/version'
3
+
4
+ module Swagger
5
+ module Blocks
6
+
7
+ # Inject the swagger_root, swagger_api_root, and swagger_model class methods.
8
+ def self.included(base)
9
+ base.extend(ClassMethods)
10
+ end
11
+
12
+ def self.build_root_json(swaggered_classes)
13
+ data = Swagger::Blocks::InternalHelpers.parse_swaggered_classes(swaggered_classes)
14
+
15
+ if data[:root_node].is_swagger_2_0?
16
+ data[:root_node].key(:paths, data[:path_nodes]) # Required, so no empty check.
17
+ if data[:schema_nodes] && !data[:schema_nodes].empty?
18
+ data[:root_node].key(:definitions, data[:schema_nodes])
19
+ end
20
+ end
21
+
22
+ data[:root_node].as_json
23
+ end
24
+ end
25
+ end
@@ -1,5 +1,5 @@
1
1
  module Swagger
2
2
  module Blocks
3
- VERSION = '1.4.0'
3
+ VERSION = '2.0.0'
4
4
  end
5
5
  end
@@ -321,10 +321,5 @@ describe 'Swagger::Blocks v2' do
321
321
  Swagger::Blocks.build_root_json([PetControllerV2, PetControllerV2])
322
322
  }.to raise_error(Swagger::Blocks::DeclarationError)
323
323
  end
324
- it 'errors if calling build_api_json' do
325
- expect {
326
- Swagger::Blocks.build_api_json('fake', [PetControllerV2])
327
- }.to raise_error(Swagger::Blocks::NotSupportedError)
328
- end
329
324
  end
330
325
  end
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: 1.4.0
4
+ version: 2.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: 2016-11-22 00:00:00.000000000 Z
11
+ date: 2016-11-30 00:00:00.000000000 Z
12
12
  dependencies:
13
13
  - !ruby/object:Gem::Dependency
14
14
  name: bundler
@@ -79,13 +79,35 @@ files:
79
79
  - Gemfile
80
80
  - LICENSE
81
81
  - README.md
82
- - README_v1_2.md
83
82
  - Rakefile
84
83
  - lib/swagger/blocks.rb
84
+ - lib/swagger/blocks/class_methods.rb
85
+ - lib/swagger/blocks/errors.rb
86
+ - lib/swagger/blocks/internal_helpers.rb
87
+ - lib/swagger/blocks/node.rb
88
+ - lib/swagger/blocks/nodes/all_of_node.rb
89
+ - lib/swagger/blocks/nodes/contact_node.rb
90
+ - lib/swagger/blocks/nodes/example_node.rb
91
+ - lib/swagger/blocks/nodes/external_docs_node.rb
92
+ - lib/swagger/blocks/nodes/header_node.rb
93
+ - lib/swagger/blocks/nodes/info_node.rb
94
+ - lib/swagger/blocks/nodes/items_node.rb
95
+ - lib/swagger/blocks/nodes/license_node.rb
96
+ - lib/swagger/blocks/nodes/operation_node.rb
97
+ - lib/swagger/blocks/nodes/parameter_node.rb
98
+ - lib/swagger/blocks/nodes/path_node.rb
99
+ - lib/swagger/blocks/nodes/properties_node.rb
100
+ - lib/swagger/blocks/nodes/property_node.rb
101
+ - lib/swagger/blocks/nodes/response_node.rb
102
+ - lib/swagger/blocks/nodes/root_node.rb
103
+ - lib/swagger/blocks/nodes/schema_node.rb
104
+ - lib/swagger/blocks/nodes/scopes_node.rb
105
+ - lib/swagger/blocks/nodes/security_requirement_node.rb
106
+ - lib/swagger/blocks/nodes/security_scheme_node.rb
107
+ - lib/swagger/blocks/nodes/tag_node.rb
108
+ - lib/swagger/blocks/nodes/xml_node.rb
109
+ - lib/swagger/blocks/root.rb
85
110
  - lib/swagger/blocks/version.rb
86
- - spec/lib/swagger_api_declaration.json
87
- - spec/lib/swagger_blocks_spec.rb
88
- - spec/lib/swagger_resource_listing.json
89
111
  - spec/lib/swagger_v2_api_declaration.json
90
112
  - spec/lib/swagger_v2_blocks_spec.rb
91
113
  - spec/spec_helper.rb
@@ -115,9 +137,6 @@ signing_key:
115
137
  specification_version: 4
116
138
  summary: Define and serve live-updating Swagger JSON for Ruby apps.
117
139
  test_files:
118
- - spec/lib/swagger_api_declaration.json
119
- - spec/lib/swagger_blocks_spec.rb
120
- - spec/lib/swagger_resource_listing.json
121
140
  - spec/lib/swagger_v2_api_declaration.json
122
141
  - spec/lib/swagger_v2_blocks_spec.rb
123
142
  - spec/spec_helper.rb
@@ -1,143 +0,0 @@
1
- # Swagger 1.2 example (Rails)
2
-
3
- **NOTE: this is old, you probably want to [use the latest syntax](https://github.com/fotinakis/swagger-blocks).**
4
-
5
- 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.
6
-
7
- Also note that Rails is not required, you can use Swagger::Blocks with any Ruby web framework.
8
-
9
- ### PetsController
10
-
11
- Parameters and features below are defined by the [Swagger 1.2 spec](https://github.com/wordnik/swagger-spec/blob/master/versions/1.2.md).
12
-
13
- ```Ruby
14
- class PetsController < ActionController::Base
15
- include Swagger::Blocks
16
-
17
- swagger_api_root :pets do
18
- key :swaggerVersion, '1.2'
19
- key :apiVersion, '1.0.0'
20
- key :basePath, 'http://petstore.swagger.wordnik.com/api'
21
- key :resourcePath, '/pets'
22
- api do
23
- key :path, '/pets/{petId}'
24
- operation do
25
- key :method, 'GET'
26
- key :summary, 'Find pet by ID'
27
- key :notes, 'Returns a pet based on ID'
28
- key :type, :Pet
29
- key :nickname, :getPetById
30
- parameter do
31
- key :paramType, :path
32
- key :name, :petId
33
- key :description, 'ID of pet that needs to be fetched'
34
- key :required, true
35
- key :type, :integer
36
- end
37
- response_message do
38
- key :code, 400
39
- key :message, 'Invalid ID supplied'
40
- end
41
- response_message do
42
- key :code, 404
43
- key :message, 'Pet not found'
44
- end
45
- end
46
- end
47
- end
48
-
49
- # ...
50
- end
51
- ```
52
-
53
- ### Pet model
54
-
55
- ```Ruby
56
- class Pet < ActiveRecord::Base
57
- include Swagger::Blocks
58
-
59
- swagger_model :Pet do
60
- key :id, :Pet
61
- key :required, [:id, :name]
62
- property :id do
63
- key :type, :integer
64
- key :format, :int64
65
- key :description, 'unique identifier for the pet'
66
- key :minimum, '0.0'
67
- key :maximum, '100.0'
68
- end
69
- property :name do
70
- key :type, :string
71
- end
72
- property :photoUrls do
73
- key :type, :array
74
- items do
75
- key :type, :string
76
- end
77
- end
78
- property :status do
79
- key :type, :string
80
- key :description, 'pet status in the store'
81
- key :enum, [:available, :pending, :sold]
82
- end
83
- end
84
-
85
- # ...
86
- end
87
- ```
88
-
89
- ### Docs controller
90
-
91
- To integrate these definitions with Swagger UI, we need a docs controller that can serve the JSON definitions.
92
-
93
- ```Ruby
94
- resources :apidocs, only: [:index, :show]
95
- ```
96
-
97
- ```Ruby
98
- class ApidocsController < ActionController::Base
99
- include Swagger::Blocks
100
-
101
- swagger_root do
102
- key :swaggerVersion, '1.2'
103
- key :apiVersion, '1.0.0'
104
- info do
105
- key :title, 'Swagger Sample App'
106
- end
107
- api do
108
- key :path, '/pets'
109
- key :description, 'Operations about pets'
110
- end
111
- end
112
-
113
- # A list of all classes that have swagger_* declarations.
114
- SWAGGERED_CLASSES = [
115
- PetsController,
116
- Pets,
117
- self,
118
- ].freeze
119
-
120
- def index
121
- render json: Swagger::Blocks.build_root_json(SWAGGERED_CLASSES)
122
- end
123
-
124
- def show
125
- render json: Swagger::Blocks.build_api_json(params[:id], SWAGGERED_CLASSES)
126
- end
127
- end
128
-
129
- ```
130
-
131
- The special part of this controller are these lines:
132
-
133
- ```Ruby
134
- render json: Swagger::Blocks.build_root_json(SWAGGERED_CLASSES)
135
- ```
136
-
137
- ```Ruby
138
- render json: Swagger::Blocks.build_api_json(params[:id], SWAGGERED_CLASSES)
139
- ```
140
-
141
- 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.
142
-
143
- 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.
@@ -1,201 +0,0 @@
1
- {
2
- "apiVersion": "1.0.0",
3
- "swaggerVersion": "1.2",
4
- "basePath": "http://petstore.swagger.wordnik.com/api",
5
- "resourcePath": "/pet",
6
- "produces": [
7
- "application/json",
8
- "application/xml",
9
- "text/plain",
10
- "text/html"
11
- ],
12
- "apis": [
13
- {
14
- "path": "/pet/{petId}",
15
- "operations": [
16
- {
17
- "method": "GET",
18
- "summary": "Find pet by ID",
19
- "notes": "Returns a pet based on ID",
20
- "type": "Pet",
21
- "nickname": "getPetById",
22
- "parameters": [
23
- {
24
- "name": "petId",
25
- "description": "ID of pet that needs to be fetched",
26
- "required": true,
27
- "type": "integer",
28
- "format": "int64",
29
- "paramType": "path",
30
- "minimum": "1.0",
31
- "maximum": "100000.0"
32
- }
33
- ],
34
- "responseMessages": [
35
- {
36
- "code": 400,
37
- "message": "Invalid ID supplied"
38
- },
39
- {
40
- "code": 404,
41
- "message": "Pet not found"
42
- }
43
- ]
44
- },
45
- {
46
- "method": "PATCH",
47
- "summary": "partial updates to a pet",
48
- "notes": "",
49
- "type": "array",
50
- "items": {
51
- "$ref": "Pet"
52
- },
53
- "nickname": "partialUpdate",
54
- "produces": [
55
- "application/json",
56
- "application/xml"
57
- ],
58
- "consumes": [
59
- "application/json",
60
- "application/xml"
61
- ],
62
- "authorizations": {
63
- "oauth2": [
64
- {
65
- "scope": "test:anything",
66
- "description": "anything"
67
- }
68
- ]
69
- },
70
- "parameters": [
71
- {
72
- "name": "petId",
73
- "description": "ID of pet that needs to be fetched",
74
- "required": true,
75
- "type": "string",
76
- "paramType": "path"
77
- },
78
- {
79
- "name": "body",
80
- "description": "Pet object that needs to be added to the store",
81
- "required": true,
82
- "type": "Pet",
83
- "paramType": "body"
84
- }
85
- ],
86
- "responseMessages": [
87
- {
88
- "code": 400,
89
- "message": "Invalid tag value"
90
- }
91
- ]
92
- }
93
- ]
94
- },
95
- {
96
- "path": "/pet/findByStatus",
97
- "operations": [
98
- {
99
- "method": "GET",
100
- "summary": "Finds Pets by status",
101
- "notes": "Multiple status values can be provided with comma seperated strings",
102
- "type": "array",
103
- "items": {
104
- "$ref": "Pet"
105
- },
106
- "nickname": "findPetsByStatus",
107
- "parameters": [
108
- {
109
- "name": "status",
110
- "description": "Status values that need to be considered for filter",
111
- "defaultValue": "available",
112
- "required": true,
113
- "type": "string",
114
- "paramType": "query",
115
- "enum": [
116
- "available",
117
- "pending",
118
- "sold"
119
- ]
120
- }
121
- ],
122
- "responseMessages": [
123
- {
124
- "code": 400,
125
- "message": "Invalid status value"
126
- }
127
- ]
128
- }
129
- ]
130
- }
131
- ],
132
- "models": {
133
- "Tag": {
134
- "id": "Tag",
135
- "properties": {
136
- "id": {
137
- "type": "integer",
138
- "format": "int64"
139
- },
140
- "name": {
141
- "type": "string"
142
- }
143
- }
144
- },
145
- "Pet": {
146
- "id": "Pet",
147
- "required": [
148
- "id",
149
- "name"
150
- ],
151
- "properties": {
152
- "id": {
153
- "type": "integer",
154
- "format": "int64",
155
- "description": "unique identifier for the pet",
156
- "minimum": "0.0",
157
- "maximum": "100.0"
158
- },
159
- "category": {
160
- "$ref": "Category"
161
- },
162
- "name": {
163
- "type": "string"
164
- },
165
- "photoUrls": {
166
- "type": "array",
167
- "items": {
168
- "type": "string"
169
- }
170
- },
171
- "tags": {
172
- "type": "array",
173
- "items": {
174
- "$ref": "Tag"
175
- }
176
- },
177
- "status": {
178
- "type": "string",
179
- "description": "pet status in the store",
180
- "enum": [
181
- "available",
182
- "pending",
183
- "sold"
184
- ]
185
- }
186
- }
187
- },
188
- "Category": {
189
- "id": "Category",
190
- "properties": {
191
- "id": {
192
- "type": "integer",
193
- "format": "int64"
194
- },
195
- "name": {
196
- "type": "string"
197
- }
198
- }
199
- }
200
- }
201
- }