Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Fix swagger warnings #865

Merged
merged 3 commits into from
Apr 14, 2023
Merged

Conversation

PanosCodes
Copy link
Contributor

Why

  • When running bundle exec rake apipie:static_swagger_json you might endup with the following error that is missing the controller name like
WARNING (105): [update] -- The parameter :street is optional but default value is not specified (use :default_value => ...)
  • When having multiple errors they are outputted without a new line like
    WARNING (105): [create] -- The parameter :zip is optional but default value is not specified (use :default_value => ...)WARNING (100): [V1::UsersController#create] -- Missing short description for methodWARNING (102): [V1::UsersController#create] -- No return codes ('errors') specifiedWARNING (107): [V1::UsersController#update] -- The parameter :id appears in the path /api/v1/users/:id but is not describedWARNING (105): [update] -- The parameter :name is optional but default value is not specified (use :default_value => ...)WARNING (105): [update] -- The parameter :street is optional but default value is not specified (use :default_value => ...)WARNING (105): [update] -- The parameter :number is optional but default value is not specified (use :default_value => ...)WARNING (105): [update] -- The parameter :zip is optional but default value is not specified (use :default_value => ...)WARNING (100): [V1::UsersController#update] -- Missing short description for method

How

  • Create a #method_name function in MethodDescription that outputs the @method attribute, when method is called inside SimpleDelegator might end up using the core ruby #method.
  • Update YARD to indicate that a MethodDescription is passed instead of a String.
  • Add a new line a the end of the warning.

@mathieujobin mathieujobin merged commit dc32905 into Apipie:master Apr 14, 2023
@PanosCodes PanosCodes deleted the fix-swagger-warnings branch April 14, 2023 18:02
h-lame added a commit to meetcleo/apipie-rails that referenced this pull request Jun 24, 2024
In Apipie#865 we introduced a `method_name` method on `MethodDescription` to avoid this bug, but the commit didn't actually use that method.  Sometimes the `@controller_method` object used is a `Apipie::Generator::Swagger::MethodDescription::Decorator` which is a `SimpleDelegate` onto a `Apipie::MethodDescription` and we'd expect to be able to call `method` on it, but unfortunately `method` is one of the things _not_ delegated by `SimpleDelegate` because it's a standard ruby method and so you get

    ArgumentError: wrong number of arguments (given 0, expected 1)

when you try to call it.  Using `method_name` instead avoids that so that's what we do - and now we can happily generate the swagger warnings when we have hash type objects without defined params.
h-lame added a commit to meetcleo/apipie-rails that referenced this pull request Jul 3, 2024
In Apipie#865 we introduced a `method_name` method on `MethodDescription` to avoid this bug, but the commit didn't actually use that method.  Sometimes the `@controller_method` object used is a `Apipie::Generator::Swagger::MethodDescription::Decorator` which is a `SimpleDelegate` onto a `Apipie::MethodDescription` and we'd expect to be able to call `method` on it, but unfortunately `method` is one of the things _not_ delegated by `SimpleDelegate` because it's a standard ruby method and so you get

    ArgumentError: wrong number of arguments (given 0, expected 1)

when you try to call it.  Using `method_name` instead avoids that so that's what we do - and now we can happily generate the swagger warnings when we have hash type objects without defined params.
h-lame added a commit to meetcleo/apipie-rails that referenced this pull request Jul 9, 2024
In Apipie#865 we introduced a `method_name` method on `MethodDescription` to avoid this bug, but the commit didn't actually use that method.  Sometimes the `@controller_method` object used is a `Apipie::Generator::Swagger::MethodDescription::Decorator` which is a `SimpleDelegate` onto a `Apipie::MethodDescription` and we'd expect to be able to call `method` on it, but unfortunately `method` is one of the things _not_ delegated by `SimpleDelegate` because it's a standard ruby method and so you get

    ArgumentError: wrong number of arguments (given 0, expected 1)

when you try to call it.  Using `method_name` instead avoids that so that's what we do - and now we can happily generate the swagger warnings when we have hash type objects without defined params.
mathieujobin pushed a commit that referenced this pull request Jul 16, 2024
…#938)

* Use `method_name` instead of `method` when generating hash warnings

In #865 we introduced a `method_name` method on `MethodDescription` to avoid this bug, but the commit didn't actually use that method.  Sometimes the `@controller_method` object used is a `Apipie::Generator::Swagger::MethodDescription::Decorator` which is a `SimpleDelegate` onto a `Apipie::MethodDescription` and we'd expect to be able to call `method` on it, but unfortunately `method` is one of the things _not_ delegated by `SimpleDelegate` because it's a standard ruby method and so you get

    ArgumentError: wrong number of arguments (given 0, expected 1)

when you try to call it.  Using `method_name` instead avoids that so that's what we do - and now we can happily generate the swagger warnings when we have hash type objects without defined params.

* Use `method_name` instead of `method` when generating required warnings

Unlike the previous commit, this isn't strictly required as we're not calling
the un-delegated `method`, but instead the warning will contain a standard
`to_s` of the `@controller_method` that isn't very easy to read, like this:

    WARNING (105): [#<Apipie::MethodDescription:0x0000000126316f60>] -- The
    parameter :param is optional but default value is not specified (use
    :default_value => ...)

By using `method_name` instead we get symmetry with the hash warning from the
previous commit.

* Fix rubocop-rspec by removing a redundant `let`

Only allowed 15 `let` or `subject`s for a given spec, and we now have 16.
Removing the `with_null` memoization lets us proceed. In theory it would have
allowed us to run the specs with_null set to both true and false, but in
practice, we weren't, and the other memoized values _were_ useful for
customising the specs.

* Handle warnings for param descriptions without a controller method

If we're generating swagger via
`SwaggerGenerator.json_schema_for_self_describing_class` we explicitly don't
have a `controller_method` being passed around so we can't use it for the
warnings. Introduce a test for type and builder to cover this scenario (first
spotted by a failing spec for `SwaggerGenerator`) and then change the
implementation to cope with it. Luckily,
`Apipie::Generator::Swagger::MethodDescription::Decorator` already had a
`ruby_name` implementation that handles being given `nil`, so we use that.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

2 participants