sober_swag 0.15.0 → 0.20.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 (55) hide show
  1. checksums.yaml +4 -4
  2. data/.github/dependabot.yml +15 -0
  3. data/.github/workflows/lint.yml +4 -9
  4. data/.github/workflows/ruby.yml +2 -6
  5. data/.gitignore +4 -0
  6. data/.rubocop.yml +50 -5
  7. data/.yardopts +7 -0
  8. data/CHANGELOG.md +29 -1
  9. data/Gemfile +8 -0
  10. data/README.md +155 -4
  11. data/bin/rspec +29 -0
  12. data/docs/serializers.md +18 -13
  13. data/example/Gemfile +2 -2
  14. data/example/app/controllers/people_controller.rb +4 -0
  15. data/example/app/controllers/posts_controller.rb +5 -0
  16. data/example/config/environments/production.rb +1 -1
  17. data/lib/sober_swag.rb +6 -1
  18. data/lib/sober_swag/compiler.rb +29 -3
  19. data/lib/sober_swag/compiler/path.rb +49 -3
  20. data/lib/sober_swag/compiler/paths.rb +20 -0
  21. data/lib/sober_swag/compiler/primitive.rb +20 -1
  22. data/lib/sober_swag/compiler/type.rb +105 -22
  23. data/lib/sober_swag/controller.rb +42 -15
  24. data/lib/sober_swag/controller/route.rb +133 -28
  25. data/lib/sober_swag/input_object.rb +117 -7
  26. data/lib/sober_swag/nodes/array.rb +19 -0
  27. data/lib/sober_swag/nodes/attribute.rb +45 -4
  28. data/lib/sober_swag/nodes/base.rb +27 -7
  29. data/lib/sober_swag/nodes/binary.rb +30 -13
  30. data/lib/sober_swag/nodes/enum.rb +16 -1
  31. data/lib/sober_swag/nodes/list.rb +20 -0
  32. data/lib/sober_swag/nodes/nullable_primitive.rb +3 -0
  33. data/lib/sober_swag/nodes/object.rb +4 -1
  34. data/lib/sober_swag/nodes/one_of.rb +11 -3
  35. data/lib/sober_swag/nodes/primitive.rb +34 -2
  36. data/lib/sober_swag/nodes/sum.rb +8 -0
  37. data/lib/sober_swag/output_object.rb +35 -4
  38. data/lib/sober_swag/output_object/definition.rb +31 -1
  39. data/lib/sober_swag/output_object/field.rb +31 -11
  40. data/lib/sober_swag/output_object/field_syntax.rb +19 -3
  41. data/lib/sober_swag/output_object/view.rb +46 -1
  42. data/lib/sober_swag/parser.rb +7 -1
  43. data/lib/sober_swag/serializer/array.rb +27 -3
  44. data/lib/sober_swag/serializer/base.rb +75 -25
  45. data/lib/sober_swag/serializer/conditional.rb +33 -1
  46. data/lib/sober_swag/serializer/field_list.rb +18 -2
  47. data/lib/sober_swag/serializer/mapped.rb +10 -1
  48. data/lib/sober_swag/serializer/optional.rb +18 -1
  49. data/lib/sober_swag/serializer/primitive.rb +3 -0
  50. data/lib/sober_swag/server.rb +27 -11
  51. data/lib/sober_swag/type/named.rb +14 -0
  52. data/lib/sober_swag/types/comma_array.rb +4 -0
  53. data/lib/sober_swag/version.rb +1 -1
  54. data/sober_swag.gemspec +2 -2
  55. metadata +13 -10
data/bin/rspec ADDED
@@ -0,0 +1,29 @@
1
+ #!/usr/bin/env ruby
2
+ # frozen_string_literal: true
3
+
4
+ #
5
+ # This file was generated by Bundler.
6
+ #
7
+ # The application 'rspec' is installed as part of a gem, and
8
+ # this file is here to facilitate running it.
9
+ #
10
+
11
+ require 'pathname'
12
+ ENV['BUNDLE_GEMFILE'] ||= File.expand_path('../../Gemfile',
13
+ Pathname.new(__FILE__).realpath)
14
+
15
+ bundle_binstub = File.expand_path('bundle', __dir__)
16
+
17
+ if File.file?(bundle_binstub)
18
+ if File.read(bundle_binstub, 300) =~ /This file was generated by Bundler/
19
+ load(bundle_binstub)
20
+ else
21
+ abort("Your `bin/bundle` was not generated by Bundler, so this binstub cannot run.
22
+ Replace `bin/bundle` by running `bundle binstubs bundler --force`, then run this command again.")
23
+ end
24
+ end
25
+
26
+ require 'rubygems'
27
+ require 'bundler/setup'
28
+
29
+ load Gem.bin_path('rspec-core', 'rspec')
data/docs/serializers.md CHANGED
@@ -25,21 +25,21 @@ For example, you might have a serializer that can return a date in two formats,
25
25
  In this case, it might be used as:
26
26
 
27
27
  ```ruby
28
- serializer.new(my_record, { format: :newstyle })
28
+ serializer.new(my_record, { format: :new_style })
29
29
  ```
30
30
 
31
31
  However, since it is *always* optional, you can also do:
32
32
 
33
33
  ```ruby
34
- serilaizer.new(my_record)
34
+ serializer.new(my_record)
35
35
  ```
36
36
 
37
37
  And it *should* pick some default format.
38
38
 
39
39
  ### Primitives
40
40
 
41
- Primitive serializers, or "identity serializers," are serializers that do nothing.
42
- They are implemented as [`SoberSwag::Serializer::Primitive`](../lib/sober_swag/serializer/primitive.rb), or as the `#primitive` method on a `OutputObject`.
41
+ Primitive serializers or "identity serializers" are serializers that do nothing.
42
+ They are implemented as [`SoberSwag::Serializer::Primitive`](../lib/sober_swag/serializer/primitive.rb), or as the `#primitive` method on an `OutputObject`.
43
43
  Since they don't do anything, they can be considered the most "basic" serializer.
44
44
 
45
45
  These serializers *do not* check types.
@@ -51,12 +51,12 @@ serializer.serialize(10) # => 10
51
51
  ```
52
52
 
53
53
  Thus, care should be used when working with these serializers.
54
- In the future, we might add some "debug mode" sorta thing that will do type-checking and throw errors, however, the cost of doing so in production is probably not worth it.
54
+ In the future, we might add some "debug mode" thing that will do type-checking and throw errors, however, the cost of doing so in production is probably not worth it.
55
55
 
56
56
  ### Mapped
57
57
 
58
58
  Sometimes, you can create a serializer via a *proc*.
59
- For example, let's say that I want a serializer that takes a `Date` and returns a string.
59
+ For example, let's say that I want a serializer that takes a `Date` and returns a String.
60
60
  I can do this:
61
61
 
62
62
  ```ruby
@@ -74,7 +74,7 @@ In the future, we might add a debug mode.
74
74
  Oftentimes, we want to give a serializer the ability to serialize `nil` values.
75
75
  This is often useful in serializing fields.
76
76
 
77
- It turns out that it's pretty easy to make a serializer that can serialize `nil` values: just propogate nils.
77
+ It turns out that it's pretty easy to make a serializer that can serialize `nil` values: just propogate `nil`s.
78
78
  For example, let's say I have the following code:
79
79
 
80
80
  ```ruby
@@ -99,7 +99,7 @@ Continuing our example from earlier:
99
99
  my_serializer.array.serialize([Foo.new(10, 11)]) #=> [{ bar: 10, baz: 11 }]
100
100
  ```
101
101
 
102
- This changes the type properly, too.
102
+ This changes the type properly too.
103
103
 
104
104
  ## OutputObjects
105
105
 
@@ -132,7 +132,7 @@ end
132
132
  We can see a few things here:
133
133
 
134
134
  1. You define field names with a `field` definition, which is a way to define the serializer for a single field.
135
- 2. You must provide types with field names
135
+ 2. You must provide types with field names.
136
136
  3. You can use blocks to do data formatting, which lets you pick different fields and such.
137
137
 
138
138
 
@@ -223,12 +223,12 @@ For clarity (and to prevent infinitely-looping serializers on accident, we recom
223
223
  Output objects don't support inheritance.
224
224
  You can't have one output object based on another.
225
225
  You *can*, however, merge one into another!
226
- Consdier this case:
226
+ Consider this case:
227
227
 
228
228
  ```ruby
229
229
  GenericBioOutput = SoberSwag::OutputObject.define do
230
230
  field :name, primitive(:String)
231
- field :brief_history, primtiive(:String)
231
+ field :brief_history, primitive(:String)
232
232
  end
233
233
 
234
234
  ExecutiveBioOutput = SoberSwag::OutputObject.define do
@@ -241,6 +241,9 @@ end
241
241
  Using `#merge` lets you add in all the fields from one output object into another.
242
242
  You can even use `merge` from within a view.
243
243
 
244
+ Exclude any unneeded fields from the merge by passing a hash:
245
+ `merge GenericBioOutput, { except: [:position] }`
246
+
244
247
  Note that `merge` does *not* copy anything but fields.
245
248
  Identifiers and views will not be copied over.
246
249
 
@@ -248,14 +251,16 @@ Identifiers and views will not be copied over.
248
251
 
249
252
  While defining a new Output Object, you *do not* have access to the definition of that output object.
250
253
  So, how do I say that one view should be an extension of another?
251
- Simple: use the `inherits:` kwarg:
254
+ Simple, use the `inherits:` kwarg:
252
255
 
253
256
  ```ruby
254
257
  BioOutput = SoberSwag::OutputObject.define do
255
258
  field :name, primitive(:String)
259
+
256
260
  view :detail do
257
261
  field :bio, primitive(:String)
258
262
  end
263
+
259
264
  view :super_detail, inherits: :detail do
260
265
  field :age, primitive(:Integer)
261
266
  end
@@ -263,4 +268,4 @@ end
263
268
  ```
264
269
 
265
270
  `inherits` will automatically merge in all the fields of the referenced view.
266
- This means that the view `super_detail` will include fields `name`, `bio`, and `age`.
271
+ This means that the view `super_detail` will include fields `name`, `bio`, and `age`.
data/example/Gemfile CHANGED
@@ -8,7 +8,7 @@ gem 'actionpack', '>= 6.0.3.2'
8
8
  # Use sqlite3 as the database for Active Record
9
9
  gem 'sqlite3', '~> 1.4'
10
10
  # Use Puma as the app server
11
- gem 'puma', '~> 4.3'
11
+ gem 'puma', '~> 5.2'
12
12
  # Build JSON APIs with ease. Read more: https://github.com/rails/jbuilder
13
13
  # gem 'jbuilder', '~> 2.7'
14
14
  # Use Active Model has_secure_password
@@ -34,7 +34,7 @@ group :development, :test do
34
34
  end
35
35
 
36
36
  group :development do
37
- gem 'listen', '>= 3.0.5', '< 3.2'
37
+ gem 'listen', '>= 3.0.5', '< 3.6'
38
38
  # Spring speeds up development by keeping your application running in the background. Read more: https://github.com/rails/spring
39
39
  gem 'spring'
40
40
  gem 'spring-watcher-listen', '~> 2.0.0'
@@ -35,6 +35,7 @@ class PeopleController < ApplicationController
35
35
  request_body(PersonParams)
36
36
  response(:ok, 'the person created', PersonOutputObject)
37
37
  response(:unprocessable_entity, 'the validation errors', PersonErrorsOutputObject)
38
+ tags 'people', 'create'
38
39
  end
39
40
  def create
40
41
  p = Person.new(parsed_body.person.to_h)
@@ -50,6 +51,7 @@ class PeopleController < ApplicationController
50
51
  path_params { attribute :id, Types::Params::Integer }
51
52
  response(:ok, 'the person updated', PersonOutputObject)
52
53
  response(:unprocessable_entity, 'the validation errors', PersonErrorsOutputObject)
54
+ tags 'people', 'update'
53
55
  end
54
56
  def update
55
57
  if @person.update(parsed_body.person.to_h)
@@ -68,6 +70,7 @@ class PeopleController < ApplicationController
68
70
  attribute :view, Types::String.default('base'.freeze).enum('base', 'detail')
69
71
  end
70
72
  response(:ok, 'all the people', PersonOutputObject.array)
73
+ tags 'people', 'list'
71
74
  end
72
75
  def index
73
76
  @people = Person.all
@@ -81,6 +84,7 @@ class PeopleController < ApplicationController
81
84
  attribute :id, Types::Params::Integer
82
85
  end
83
86
  response(:ok, 'the person requested', PersonOutputObject)
87
+ tags 'people', 'show'
84
88
  end
85
89
  def show
86
90
  respond!(:ok, @person)
@@ -47,6 +47,7 @@ class PostsController < ApplicationController
47
47
  MARKDOWN
48
48
  end
49
49
  response(:ok, 'all the posts', PostOutputObject.array)
50
+ tags 'posts', 'list'
50
51
  end
51
52
  def index
52
53
  @posts = Post.all
@@ -60,6 +61,7 @@ class PostsController < ApplicationController
60
61
  path_params(ShowPath)
61
62
  query_params { attribute? :view, ViewTypes }
62
63
  response(:ok, 'the requested post', PostOutputObject)
64
+ tags 'posts', 'show'
63
65
  end
64
66
  def show
65
67
  respond!(:ok, @post, serializer_opts: { view: parsed_query.view })
@@ -68,6 +70,7 @@ class PostsController < ApplicationController
68
70
  define :post, :create, '/posts/' do
69
71
  request_body(PostCreate)
70
72
  response(:created, 'the created post', PostOutputObject)
73
+ tags 'posts', 'create'
71
74
  end
72
75
  def create
73
76
  @post = Post.new(parsed_body.post.to_h)
@@ -83,6 +86,7 @@ class PostsController < ApplicationController
83
86
  path_params(ShowPath)
84
87
  request_body(PostUpdate)
85
88
  response(:ok, 'the post updated', PostOutputObject.view(:base))
89
+ tags 'posts', 'update'
86
90
  end
87
91
  def update
88
92
  if @post.update(parsed_body.post.to_h)
@@ -95,6 +99,7 @@ class PostsController < ApplicationController
95
99
  define :delete, :destroy, '/posts/{id}' do
96
100
  path_params(ShowPath)
97
101
  response(:ok, 'the post deleted', PostOutputObject.view(:base))
102
+ tags 'posts', 'delete'
98
103
  end
99
104
  def destroy
100
105
  @post.destroy
@@ -60,7 +60,7 @@ Rails.application.configure do
60
60
  # config.logger = ActiveSupport::TaggedLogging.new(Syslog::Logger.new 'app-name')
61
61
 
62
62
  if ENV['RAILS_LOG_TO_STDOUT'].present?
63
- logger = ActiveSupport::Logger.new(STDOUT)
63
+ logger = ActiveSupport::Logger.new($stdout)
64
64
  logger.formatter = config.log_formatter
65
65
  config.logger = ActiveSupport::TaggedLogging.new(logger)
66
66
  end
data/lib/sober_swag.rb CHANGED
@@ -9,8 +9,10 @@ require 'sober_swag/version'
9
9
  require 'active_support/inflector'
10
10
 
11
11
  ##
12
- # Root namespace
12
+ # Root namespace for the SoberSwag Module.
13
13
  module SoberSwag
14
+ ##
15
+ # Root Error Class for SoberSwag errors.
14
16
  class Error < StandardError; end
15
17
 
16
18
  autoload :Parser, 'sober_swag/parser'
@@ -26,7 +28,10 @@ module SoberSwag
26
28
  ##
27
29
  # Define a struct of something.
28
30
  # Useful to prevent weirdness from autoloading.
31
+ #
29
32
  # @param parent [Class] the base class for the struct (default of {SoberSwag::Struct})
33
+ # @yieldself [SoberSwag::InputObject]
34
+ # @return [Class] the input object class generated
30
35
  def self.input_object(parent = nil, &block)
31
36
  Class.new(parent || SoberSwag::InputObject, &block)
32
37
  end
@@ -17,6 +17,8 @@ module SoberSwag
17
17
 
18
18
  ##
19
19
  # Convert a compiler to the overall type definition.
20
+ #
21
+ # @return Hash the swagger definition.
20
22
  def to_swagger
21
23
  {
22
24
  paths: path_schemas,
@@ -29,16 +31,23 @@ module SoberSwag
29
31
  ##
30
32
  # Add a path to be compiled.
31
33
  # @param route [SoberSwag::Controller::Route] the route to add.
34
+ # @return [Compiler] self
32
35
  def add_route(route)
33
36
  tap { @paths.add_route(route) }
34
37
  end
35
38
 
39
+ ##
40
+ # Get the schema of each object type defined in this Compiler.
41
+ #
42
+ # @return [Hash]
36
43
  def object_schemas
37
44
  @types.map { |v| [v.ref_name, v.object_schema] }.to_h
38
45
  end
39
46
 
40
47
  ##
41
48
  # The path section of the swagger schema.
49
+ #
50
+ # @return [Hash]
42
51
  def path_schemas
43
52
  @paths.paths_list(self)
44
53
  end
@@ -46,6 +55,9 @@ module SoberSwag
46
55
  ##
47
56
  # Compile a type to a new, path-params list.
48
57
  # This will add all subtypes to the found types list.
58
+ #
59
+ # @param type [Class] the type to get a path_params definition for
60
+ # @return [Hash]
49
61
  def path_params_for(type)
50
62
  with_types_discovered(type).path_schema
51
63
  end
@@ -53,6 +65,9 @@ module SoberSwag
53
65
  ##
54
66
  # Get the query params list for a type.
55
67
  # All found types will be added to the reference dictionary.
68
+ #
69
+ # @param type [Class] the type to get the query_params definitions for
70
+ # @return [Hash]
56
71
  def query_params_for(type)
57
72
  with_types_discovered(type).query_schema
58
73
  end
@@ -60,25 +75,36 @@ module SoberSwag
60
75
  ##
61
76
  # Get the request body definition for a type.
62
77
  # This will always be a ref.
78
+ #
79
+ # @param type [Class] the type to get the body definition for
80
+ # @return [Hash]
63
81
  def body_for(type)
64
82
  add_type(type)
65
83
  Type.new(type).schema_stub
66
84
  end
67
85
 
68
86
  ##
69
- # Get the definition of a response type
87
+ # Get the definition of a response type.
88
+ #
89
+ # This is an alias of {#body_for}
90
+ # @see body_for
70
91
  def response_for(type)
71
92
  body_for(type)
72
93
  end
73
94
 
74
95
  ##
75
- # Get the existing schema for a given type
96
+ # Get the existing schema for a given type.
97
+ #
98
+ # @param type [Class] the type to get the schema for
99
+ # @return [Hash,nil] the swagger schema for this object, or nil if it was not found.
76
100
  def schema_for(type)
77
101
  @types.find { |type_comp| type_comp.type == type }&.object_schema
78
102
  end
79
103
 
80
104
  ##
81
- # Add a type in the types reference dictionary, essentially
105
+ # Add a type in the types reference dictionary, essentially.
106
+ # @param type [Class] the type to compiler
107
+ # @return [SoberSwag::Compiler] self
82
108
  def add_type(type)
83
109
  # use tap here to avoid an explicit self at the end of this
84
110
  # which makes this method chainable
@@ -1,8 +1,11 @@
1
1
  module SoberSwag
2
2
  class Compiler
3
3
  ##
4
- # Compile a singular path, and that's it.
5
- # Only handles the actual body.
4
+ # This compiler transforms a {SoberSwag::Controller::Route} object into its associated OpenAPI V3 definition.
5
+ # These definitions are [called "paths" in the OpenAPI V3 spec](https://swagger.io/docs/specification/paths-and-operations/),
6
+ # thus the name of this compiler.
7
+ #
8
+ # It only compiles a *single* "path" at a time.
6
9
  class Path
7
10
  ##
8
11
  # @param route [SoberSwag::Controller::Route] a route to use
@@ -12,8 +15,18 @@ module SoberSwag
12
15
  @compiler = compiler
13
16
  end
14
17
 
15
- attr_reader :route, :compiler
18
+ ##
19
+ # @return [SoberSwag::Controller::Route]
20
+ attr_reader :route
21
+
22
+ ##
23
+ # @return [SoberSwag::Compiler] the compiler used for type compilation
24
+ attr_reader :compiler
16
25
 
26
+ ##
27
+ # The OpenAPI V3 "path" object for the associated {SoberSwag::Controller::Route}
28
+ #
29
+ # @return [Hash] the OpenAPI V3 description
17
30
  def schema
18
31
  base = {}
19
32
  base[:summary] = route.summary if route.summary
@@ -21,9 +34,15 @@ module SoberSwag
21
34
  base[:parameters] = params if params.any?
22
35
  base[:responses] = responses
23
36
  base[:requestBody] = request_body if request_body
37
+ base[:tags] = tags if tags
24
38
  base
25
39
  end
26
40
 
41
+ ##
42
+ # An array of "response" objects from swagger.
43
+ #
44
+ # @return [Hash{String => Hash}]
45
+ # response code to response object.
27
46
  def responses # rubocop:disable Metrics/MethodLength
28
47
  route.response_serializers.map { |status, serializer|
29
48
  [
@@ -40,10 +59,19 @@ module SoberSwag
40
59
  }.to_h
41
60
  end
42
61
 
62
+ ##
63
+ # An array of all parameters, be they in the query or in the path.
64
+ # See [this page](https://swagger.io/docs/specification/serialization/) for what that looks like.
65
+ #
66
+ # @return [Array<Hash>]
43
67
  def params
44
68
  query_params + path_params
45
69
  end
46
70
 
71
+ ##
72
+ # An array of schemas for all query parameters.
73
+ #
74
+ # @return [Array<Hash>] the schemas
47
75
  def query_params
48
76
  if route.query_params_class
49
77
  compiler.query_params_for(route.query_params_class)
@@ -52,6 +80,10 @@ module SoberSwag
52
80
  end
53
81
  end
54
82
 
83
+ ##
84
+ # An array of schemas for all path parameters.
85
+ #
86
+ # @return [Array<Hash>] the schemas
55
87
  def path_params
56
88
  if route.path_params_class
57
89
  compiler.path_params_for(route.path_params_class)
@@ -60,6 +92,11 @@ module SoberSwag
60
92
  end
61
93
  end
62
94
 
95
+ ##
96
+ # The schema for a request body.
97
+ # Matches [this spec.](https://swagger.io/docs/specification/paths-and-operations/)
98
+ #
99
+ # @return [Hash] the schema
63
100
  def request_body
64
101
  return nil unless route.request_body_class
65
102
 
@@ -72,6 +109,15 @@ module SoberSwag
72
109
  }
73
110
  }
74
111
  end
112
+
113
+ ##
114
+ # The tags for this path.
115
+ # @return [Array<String>] the tags
116
+ def tags
117
+ return nil unless route.tags.any?
118
+
119
+ route.tags
120
+ end
75
121
  end
76
122
  end
77
123
  end