Improve enum values for Enum Type in Swagger ReadOnly documentation #4191

dedece35 · 2018-02-04T23:19:50Z

SwaggerUI documentation in ReadOnly mode gives :

the available values of an "Enum" type
default value
example value
From improvement Adding enum values for Enum Type in Swagger ReadOnly documentation #3977

One enum items representation wasn't considered in swagger.json
Currently considered in swagger.json :
... "parameters": [ { "name": "status", "in": "query", "description": "Status values that need to be considered for filter", "required": true, "type": "array", "items": { "type": "string", "enum": [ "available", "pending", "sold" ], "default": "available", "example": "pending" }, "collectionFormat": "multi" } ], ...

Not considered in swagger.json (example swagger.json generated from swagger annotations in Java code) - there is no "items" structure for "enum" values :
... "parameters": [ { "name": "stockstatus", "in": "query", "description": "stock status values that need to be considered for filter", "required": false, "type": "string", "default": "full", "x-example": "empty", "enum": [ "empty", "halfempty", "full" ] } ], ...

Description

rename variables for enum managment
add managment for new structure ("enum", "x-example", "default")
add example json swagger ("swagger-petstore-enum.json") for developers (we can now add "http://localhost:3200/swagger-petstore-enum.json" to test new path added for this feature ("/store/findByStock") )

Motivation and Context

As I described in my old PR #3977 , I think it's good idea to have access to default value, example value et availables values in readonly mode (not in TryItOut mode).
This PR is able to solve a new situation in swagger.json (enum values can be out of "items" structure)

~~There is NO issue for this feature~~

Fixes #2873.

How Has This Been Tested?

I tested in the same way as my old PR #3977

"npm test" results :
236 passing (744ms) 11 pending

Screenshots (if appropriate):

the red square zone is the result with new path added ("/store/findByStock") and new Enum values managment

Checklist

My PR contains...

No code changes (src/ is unmodified: changes to documentation, CI, metadata, etc.)
Dependency changes (any modification to dependencies in package.json)
Bug fixes (non-breaking change which fixes an issue)
Improvements (misc. changes to existing features)
Features (non-breaking change which adds functionality)

My changes...

are breaking changes to a public API (config options, System API, major UI change, etc).
are breaking changes to a private API (Redux, component props, utility functions, etc.).
are breaking changes to a developer API (npm script behavior changes, new dev system dependencies, etc).
are not breaking changes.

Documentation

My changes do not require a change to the project documentation.
My changes require a change to the project documentation.
If yes to above: I have updated the documentation accordingly.

Automated tests

My changes can not or do not need to be tested.
My changes can and should be tested by unit and/or integration tests.
If yes to above: I have added tests to cover my changes.
If yes to above: I have taken care to cover edge cases in my tests.
All new and existing tests passed.

…ptimisation) and also adding default/example value

…nother way to have enums values in swagger.json)

dedece35 · 2018-02-16T14:36:43Z

do you have some news about this pull request ?

dedece35 · 2018-02-20T09:05:41Z

@shockey ? :)

webron · 2018-02-20T14:57:34Z

@dedece35 we've slated time next week to address open PRs, check their functionality, give feedback, and merge if appropriate. Thanks for submitting the PR, and thanks for waiting. We appreciate the community contributions, just a bit overwhelmed with work :)

dedece35 · 2018-02-22T21:52:14Z

@webron OK ... thanks for your answer :)

dedece35 · 2018-03-18T20:05:38Z

@webron I let myself to revive you about my pull-request :)
I'm really expecting a lot of this PR to integrate it in dev in many REST APIs in my french society.

thanks again :)

webron · 2018-03-19T18:40:45Z

@dedece35 - I'm willing to go ahead and merge it (pending code review) for the functionality - but keep in mind that we may change it completely in the future. The need is understandable, which is why I think we should move forward with it, but design wise it may not be the best solution (no offense).

shockey · 2018-03-23T02:23:31Z

dev-helpers/swagger-petstore-enum.json

@@ -0,0 +1,1079 @@
+{


Is there any particular reason this file was added?

hello @shockey, this file is a simple copy of original http://petstore.swagger.io/v2/swagger.json with a new use case for enum values. In original swagger-petstore.json you can find enum values inside "get/parameters/items" ressource (example with path "/pet/findByStatus"). In the new swagger JSON file, "enum" values can appear in "get/parameters" and not only in "items" ressource (example with path "/pet/findByStock"). Indeed, this file is for testing to check enum values are also processed if are'nt inside "items" ressource : developer can use http://localhost:3200/swagger-petstore-enum.json to see the swagger-ui rendering

shockey · 2018-03-23T02:24:00Z

src/core/components/parameter-row.jsx

-
-    if (isDisplayParamItemsEnum) { // if we have an array, default value is in "items"
-      paramDefaultValue = paramItems.get("default")
+      if (paramExample == undefined) {


Should use === instead of ==

ok, no problem.

shockey · 2018-03-23T02:24:24Z

src/core/components/parameter-row.jsx

-        isDisplayParamItemsEnum = true
+
+    if ( paramEnum !== undefined ) {
+      if (paramEnum.size > 0) {


These two conditionals should be collapsed into one if statement

ok, no problem.

shockey · 2018-03-23T02:26:17Z

src/core/components/parameter-row.jsx

-    if ( paramItems !== undefined ) {
-      paramItemsEnum = param.get("items").get("enum")
+
+    if (paramItems !== undefined) {


These statements should be inverted: the if statement should have a positive condition (paramItems === undefined) and the else statement should be used for the negative case.

in this condition, I have no positive case : I only want to do things in negative case. I can't translate this condition in positive way.

dedece35

@shockey changes done.

the purpose of this file lives on in the e2e test specs folder

shockey · 2018-04-06T22:50:14Z

thanks @dedece35! 😄

dedece35 · 2018-04-07T19:25:42Z

thanks to you :)

dedece35 and others added 10 commits December 2, 2017 23:01

Adding enum values for Enum Type in Swagger ReadOnly documentation

d58ecc9

Merge branch 'master' into master

3a6b5b1

Merge remote-tracking branch 'upstream/master'

8ee3c6d

Adding enum values for Enum Type in Swagger ReadOnly documentation (o…

da75e3c

…ptimisation) and also adding default/example value

Merge branch 'master' into master

cdf57e4

Merge branch 'master' into master

fff710d

Conflict from original github repo

3ac1a3c

Add new display enums, defaults, and examples when not in TIO mode (a…

c17b02c

…nother way to have enums values in swagger.json)

Fix npm test result

6aba5d1

Merge branch 'master' into master

a2d863a

dedece35 added 2 commits February 16, 2018 15:36

Merge branch 'master' into master

34761b0

Merge branch 'master' into master

7f6c814

dedece35 added 4 commits March 6, 2018 00:09

Merge branch 'master' into master

6bcda39

Merge branch 'master' into master

d7bc198

Merge branch 'master' into master

dc63157

Merge branch 'master' into master

ebb765b

shockey suggested changes Mar 23, 2018

View reviewed changes

dedece35 and others added 2 commits March 23, 2018 16:30

Merge branch 'master' into master

7e07e1f

review corrections

fa09a29

dedece35 commented Mar 23, 2018

View reviewed changes

dedece35 added 3 commits March 24, 2018 13:50

Merge branch 'master' into master

3d93e5a

Merge branch 'master' into master

2120836

Merge branch 'master' into master

50fdc65

dedece35 mentioned this pull request Mar 28, 2018

Display enums in parameter info #3873

Closed

shockey added 11 commits April 5, 2018 17:46

Merge branch 'master' into master

3f45283

fix: don't render parameter description if field is empty

bac5e7d

use cross-version schema variable to access properties

b36b641

pass className through Markdown component usage

9d02ee8

add per-field classNames to Markdown for easier styling + testing

a43d109

remove parameter Example field (out-of-scope for this PR)

240db57

get default value from schema instead of top-level parameter

e5dc422

tests: add e2e cases for swagger2 and oas3

2de8448

remove swagger-petstore-enum.json

1ac4be3

the purpose of this file lives on in the e2e test specs folder

add missing proptypes validation

8f1356e

use classnames to more effectively union class names

16932d2

shockey approved these changes Apr 6, 2018

View reviewed changes

shockey merged commit 39d3452 into swagger-api:master Apr 6, 2018

dedece35 mentioned this pull request Apr 9, 2018

Display example value in Swagger ReadOnly documentation #4422

Merged

17 tasks

aganzha mentioned this pull request Apr 9, 2018

Fix model rendering for parameters #4424

Merged

17 tasks

shockey mentioned this pull request Apr 17, 2018

Default value from within schema is not showing in the documentation swagger-api/swagger-editor#1686

Closed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Improve enum values for Enum Type in Swagger ReadOnly documentation #4191

Improve enum values for Enum Type in Swagger ReadOnly documentation #4191

dedece35 commented Feb 4, 2018 •

edited by shockey

dedece35 commented Feb 16, 2018

dedece35 commented Feb 20, 2018

webron commented Feb 20, 2018

dedece35 commented Feb 22, 2018

dedece35 commented Mar 18, 2018

webron commented Mar 19, 2018

shockey Mar 23, 2018

dedece35 Mar 23, 2018 •

edited

shockey Mar 23, 2018

dedece35 Mar 23, 2018 •

edited

shockey Mar 23, 2018

dedece35 Mar 23, 2018 •

edited

shockey Mar 23, 2018

dedece35 Mar 23, 2018 •

edited

dedece35 left a comment •

edited

shockey commented Apr 6, 2018

dedece35 commented Apr 7, 2018

Improve enum values for Enum Type in Swagger ReadOnly documentation #4191

Improve enum values for Enum Type in Swagger ReadOnly documentation #4191

Conversation

dedece35 commented Feb 4, 2018 • edited by shockey

Description

Motivation and Context

How Has This Been Tested?

Screenshots (if appropriate):

Checklist

My PR contains...

My changes...

Documentation

Automated tests

dedece35 commented Feb 16, 2018

dedece35 commented Feb 20, 2018

webron commented Feb 20, 2018

dedece35 commented Feb 22, 2018

dedece35 commented Mar 18, 2018

webron commented Mar 19, 2018

shockey Mar 23, 2018

Choose a reason for hiding this comment

dedece35 Mar 23, 2018 • edited

Choose a reason for hiding this comment

shockey Mar 23, 2018

Choose a reason for hiding this comment

dedece35 Mar 23, 2018 • edited

Choose a reason for hiding this comment

shockey Mar 23, 2018

Choose a reason for hiding this comment

dedece35 Mar 23, 2018 • edited

Choose a reason for hiding this comment

shockey Mar 23, 2018

Choose a reason for hiding this comment

dedece35 Mar 23, 2018 • edited

Choose a reason for hiding this comment

dedece35 left a comment • edited

Choose a reason for hiding this comment

shockey commented Apr 6, 2018

dedece35 commented Apr 7, 2018

dedece35 commented Feb 4, 2018 •

edited by shockey

dedece35 Mar 23, 2018 •

edited

dedece35 Mar 23, 2018 •

edited

dedece35 Mar 23, 2018 •

edited

dedece35 Mar 23, 2018 •

edited

dedece35 left a comment •

edited