Allow enum parameter description. (#201) #429

masamichhhhi · 2021-05-30T12:56:18Z

Currently, enum query parameter can't have description about each value as mentioned in #201 .
To handle this, I added method that generating json like OAI/OpenAPI-Specification#348 (comment).

the following code

parameter name: :foo, in: :query, enum: {'bar': 'lists bars', 'baz': 'lists people named baz'}, description: "this is foo"

generates following json and documents.

{
  "name": "foo",
  "in": "query",
  "enum": {
    "bar": "lists bars",
    "baz": "lists people named baz"
  },
  "description": "this is foo\n * `bar` lists bars\n * `baz` lists people named baz\n "
}

gabrielmansour · 2021-09-29T16:24:58Z

I would like to see the Gem support enum values being automatically appended to the main description of a schema object too, but in my case, the enum is just a simple array. e.g.: enum: ['apples', 'oranges', 'bananas']

kwent · 2022-08-16T15:05:46Z

Can we merge this ? 🙏🏻

gabrielmansour · 2022-08-17T05:47:44Z

Would be nice if the option to append the enums to the description were behind a configuration flag, so they can be turned on or off, depending on preference

jtannas · 2022-11-27T21:05:52Z

Hi @masamichhhhi
Apologies for the delay in looking into this. I like the idea and will be happy to merge once there's an accompanying Changelog entry and the latest master is merged so we can see the results of our CI suite.

Edit: It looks like the official OAS doesn't support per-enum-value descriptions https://swagger.io/docs/specification/data-models/enums/
Maybe we restrict the changes to just a description on the enum parameter?

masamichhhhi · 2022-12-10T14:39:02Z

@jtannas
Thanks for your confirming! I added the CHANGELOG, please check it.

Edit: It looks like the official OAS doesn't support per-enum-value descriptions https://swagger.io/docs/specification/data-models/enums/
Maybe we restrict the changes to just a description on the enum parameter?

The document you are referring to appears to contain a statement about per-enum-description. Is there any problem with adding that?

mattpolito · 2023-05-07T23:54:46Z

@romanblanco What's the status on this PR? It appears good to go with the exception of some documentation.

romanblanco · 2023-05-08T09:40:27Z

@mattpolito, I believe the changes are ready to be merged once the PR is updated and rebased.

@masamichhhhi would you add the statement about per-enum-description to README.md together with some examples into README.md and test-app to demonstrate how to use the feature?

…ion-for-rswag#201

masamichhhhi · 2023-06-17T08:18:18Z

@romanblanco
added the statement about per-enum-description and fixed rspec of test-app to use this functionality. Let me know If there are any other changes needed to release.

romanblanco · 2023-11-14T20:53:13Z

@masamichhhhi Some of the test-app specs are still failing.

masamichhhhi · 2024-03-10T09:01:32Z

@romanblanco
I ran ci/test.sh in my environment and it appears that there are no tests that are failing (although there are tests in pending status.)
Is it possible for you to tell me which test is failing? 🙏

ci/test.sh
####################
Unit Tests
####################

##### rswag-api #####
..................

Finished in 0.01456 seconds (files took 0.43363 seconds to load)
18 examples, 0 failures

Coverage report generated for RSpec to /workspace/rswag/rswag-api/coverage. 73 / 73 LOC (100.0%) covered.
##### rswag-specs #####
........................................................................................................................................

Finished in 0.07683 seconds (files took 0.51735 seconds to load)
136 examples, 0 failures

Coverage report generated for RSpec to /workspace/rswag/rswag-specs/coverage. 549 / 568 LOC (96.65%) covered.
##### rswag-ui #####
......

Finished in 0.00903 seconds (files took 0.43286 seconds to load)
6 examples, 0 failures

Coverage report generated for RSpec to /workspace/rswag/rswag-ui/coverage. 37 / 42 LOC (88.1%) covered.
####################
Integration Tests
####################

##### test-app #####
DEPRECATION WARNING: Non-URL-safe CSRF tokens are deprecated. Use 6.1 defaults or above. (called from <top (required)> at /workspace/rswag/test-app/spec/rails_helper.rb:9)
DEPRECATION WARNING: Using legacy connection handling is deprecated. Please set
`legacy_connection_handling` to `false` in your application.

The new connection handling does not support `connection_handlers`
getter and setter.

Read more about how to migrate at: https://guides.rubyonrails.org/active_record_multiple_databases.html#migrate-to-the-new-connection-handling
 (called from load at /Path/to/ruby/bin/rspec:23)
*.......................*......*/Path/to/ruby/bin/ruby -I/Path/to/ruby/lib/ruby/gems/2.7.0/gems/rspec-core-3.13.0/lib:/Path/to/ruby/lib/ruby/gems/2.7.0/gems/rspec-support-3.13.1/lib /Path/to/ruby/lib/ruby/gems/2.7.0/gems/rspec-core-3.13.0/exe/rspec --pattern spec/requests/\*\*/\*_spec.rb,\ spec/api/\*\*/\*_spec.rb,\ spec/integration/\*\*/\*_spec.rb --format Rswag::Specs::SwaggerFormatter --order defined
DEPRECATION WARNING: Non-URL-safe CSRF tokens are deprecated. Use 6.1 defaults or above. (called from <top (required)> at /workspace/rswag/test-app/spec/rails_helper.rb:9)
Generating Swagger docs ...
DEPRECATION WARNING: Using legacy connection handling is deprecated. Please set
`legacy_connection_handling` to `false` in your application.

The new connection handling does not support `connection_handlers`
getter and setter.

Read more about how to migrate at: https://guides.rubyonrails.org/active_record_multiple_databases.html#migrate-to-the-new-connection-handling
 (called from block (2 levels) in <class:Railtie> at /Path/to/ruby/lib/ruby/gems/2.7.0/gems/activerecord-7.0.1/lib/active_record/railtie.rb:274)
Swagger doc generated at /workspace/rswag/test-app/swagger/v1/swagger.json
Swagger doc generated at /workspace/rswag/test-app/swagger/v3/openapi.json

Pending: (Failures listed here are expected and do not affect your suite's status)

  1) Generated OpenApi Media Types /stubs get OK declares output as application/json
     # Not yet implemented?
     Failure/Error: expect(tree).to have_key('application/json')
       expected nil to respond to `has_key?`
     # ./spec/integration/openapi3_spec.rb:106:in `block (6 levels) in <top (required)>'

  2) Generated OpenApi Request Body /stubs post OK declares requestBody is required
     # This output is massaged in SwaggerFormatter#stop, and isn't quite ready here to assert
     Failure/Error: expect(tree[:required]).to eq(true)

     NoMethodError:
       undefined method `[]' for nil:NilClass
     # ./spec/integration/openapi3_spec.rb:199:in `block (6 levels) in <top (required)>'

Finished in 0.35537 seconds (files took 1.15 seconds to load)
31 examples, 0 failures, 2 pending

Coverage report generated for RSpec to /workspace/rswag/test-app/coverage. 67 / 69 LOC (97.1%) covered.
.

Pending: (Failures listed here are expected and do not affect your suite's status)

  1) swagger-ui browsing api-docs
     # Needs work to run on others' machines
     # ./spec/features/swagger_ui_spec.rb:5

  2) Generated OpenApi Media Types /stubs get OK declares output as application/json
     # Not yet implemented?
     Failure/Error: expect(tree).to have_key('application/json')
       expected nil to respond to `has_key?`
     # ./spec/integration/openapi3_spec.rb:106:in `block (6 levels) in <top (required)>'

  3) Generated OpenApi Request Body /stubs post OK declares requestBody is required
     # This output is massaged in SwaggerFormatter#stop, and isn't quite ready here to assert
     Failure/Error: expect(tree[:required]).to eq(true)

     NoMethodError:
       undefined method `[]' for nil:NilClass
     # ./spec/integration/openapi3_spec.rb:199:in `block (6 levels) in <top (required)>'

Finished in 2.18 seconds (files took 1.19 seconds to load)
33 examples, 0 failures, 3 pending

(The local path is masked.)

masamichhhhi added 2 commits May 30, 2021 21:27

add logic that generate enum description

1140183

add rspec with enum parameters

5d157bb

masamichhhhi marked this pull request as ready for review May 30, 2021 12:58

masamichhhhi and others added 2 commits December 10, 2022 19:11

Merge branch 'rswag:master' into add-enum-description-for-rswag#201

ee5f73e

CHANGELOG for enum parameter description fix.

bf9f712

romanblanco added the enhancement label Mar 18, 2023

romanblanco added this to the Gem 2.X.0 milestone Apr 1, 2023

romanblanco linked an issue Apr 2, 2023 that may be closed by this pull request

feature request: enum description #201

Closed

masamichhhhi added 4 commits May 25, 2023 22:19

Merge remote-tracking branch 'upstream/master' into add-enum-descript…

d5ea1fb

…ion-for-rswag#201

change status as enum

bedd1c3

fix spec in test-app to generate enum description

dca9df1

update readme to add enum description section

ea9dcd1

Merge branch 'master' into HEAD

30ca2a8

romanblanco and others added 3 commits December 16, 2023 19:25

Merge branch 'master' into add-enum-description-for-rswag#201

7edb856

fix: corrected enum definition

9d51dc4

rerun ci

0cbb08c

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Allow enum parameter description. (#201) #429

Allow enum parameter description. (#201) #429

masamichhhhi commented May 30, 2021

gabrielmansour commented Sep 29, 2021

kwent commented Aug 16, 2022

gabrielmansour commented Aug 17, 2022

jtannas commented Nov 27, 2022 •

edited

masamichhhhi commented Dec 10, 2022

mattpolito commented May 7, 2023

romanblanco commented May 8, 2023

masamichhhhi commented Jun 17, 2023

romanblanco commented Nov 14, 2023

masamichhhhi commented Mar 10, 2024 •

edited

Allow enum parameter description. (#201) #429

Are you sure you want to change the base?

Allow enum parameter description. (#201) #429

Conversation

masamichhhhi commented May 30, 2021

gabrielmansour commented Sep 29, 2021

kwent commented Aug 16, 2022

gabrielmansour commented Aug 17, 2022

jtannas commented Nov 27, 2022 • edited

masamichhhhi commented Dec 10, 2022

mattpolito commented May 7, 2023

romanblanco commented May 8, 2023

masamichhhhi commented Jun 17, 2023

romanblanco commented Nov 14, 2023

masamichhhhi commented Mar 10, 2024 • edited

jtannas commented Nov 27, 2022 •

edited

masamichhhhi commented Mar 10, 2024 •

edited