Leave any issues you found during testing 2.0.0-alpha.x releases here (just not to make so much noise in https://github.com/Rebilly/ReDoc/issues/327)
RomanHotsiy
All 97 comments
Awesome job :)
My swagger definition does not work yet: https://cloud.squidex.io/api/swagger/v1/swagger.json
SebastianStehle
on 23 Nov 2017
@SebastianStehle your spec is failing during converting it to OpenAPI 3 using swagger2openapi because you have combination of collectionFormat and type: file while collectionFormat is supposed to be used only with type: array:
RomanHotsiy
on 23 Nov 2017
@RomanGotsiy are you passing options.patch and options.warnOnly in the conversion? I'd recommend it! Full options documentation.
MikeRalphson
on 23 Nov 2017
Ok, I fixed it and there are no more warnings in the swagger editor:
Now I get another error.
SebastianStehle
on 23 Nov 2017
@MikeRalphson thanks for the suggestion! I will enable those options in the next alpha!
@SebastianStehle yes, I can see this issue too. It is also indirectly caused by conversion process. I am now discussing the best ways to fix it with @MikeRalphson.
It will be definitelly resolved in the next alpha.
Right now I've workaround it by replacing all type: file in responses by
type: string
format: binary
You can check workarounded spec here
RomanHotsiy
on 23 Nov 2017
But with the updated spec I get the other error. But I am pretty sure that you will solve it :)
SebastianStehle
on 23 Nov 2017
But with the updated spec I get the other error. But I am pretty sure that you will solve it :)
You need to patch out the collectionFormat issue again in @RomanGotsiy 's copy to work around both issues.
MikeRalphson
on 23 Nov 2017
Oh, sorry. Thats awesome. Even some of my problems with the stable version are fixed :)
SebastianStehle
on 23 Nov 2017
I've just published v2.0.0-alpha.2 with those issues resolved.
RomanHotsiy
on 23 Nov 2017
Works perfectly for my original definition :)
SebastianStehle
on 23 Nov 2017
@RomanGotsiy I talked with you about this issue a few weeks ago on Twitter and I put another example at https://github.com/mikunn/openapi-test-allof/blob/master/allof.yaml.
So the issue is that properties in nested allOfs get lost. Running that specs shows only the meta property in the response and href and location are lost.
We reuse lots of stuffs in our specs, so that's why we have allOfs all over the place. We can probably use a separate merger before feeding the spec to ReDoc, but would be nice to get a support directly from ReDoc :)
Respect the effort as always! The docs seem crazy responsive 👍
mikunn
on 23 Nov 2017
Hey @mikunn,
thanks for reminding me! Thanks to your precise examples, it was very easy for me to reproduce the issues and to fix them both in v2.0.0-alpha.3!
Thanks, @mikunn!
RomanHotsiy
on 23 Nov 2017
Great work. Thanks!
Does the new react ReDoc works with multiple specs?
I used the same multiple example html as with 1.x.x. version. The first Redoc.init works fine, but the onClick Redoc.init(url); doesn't do anything. Any idea how I can fix it or any workaround?
// initially render first API
Redoc.init(apis[0].url);
function onClick() {
var url = this.getAttribute('data-link');
Redoc.init(url);
}
suds-kumar
on 23 Nov 2017
Fantastic! Thanks for the fast fix, @RomanGotsiy, works perfectly!
I still have another issue where ReDoc doesn't start at all displaying error "Cannot read property '$ref' of undefined". I created a new repo again at https://github.com/mikunn/openapi-test-refs. swagger.yaml is the main file. The issue is very hard to reproduce from scratch and I tried to simplify a real failing spec as much as possible.
The issue appears when there are complex $refs and, again, allOf has probably something to do with it. If you remove pretty much any $ref from any of the schemas.yaml file, it starts working. Also, if you comment out either path in the swagger.yaml file, it starts working.
Maybe there are too many references to the same file (probably root schemas.yaml) from many places and ReDoc loses track at some point?
This issue is in alpha-1 as well, so recent changes didn't break it.
mikunn
on 24 Nov 2017
@mikunn I'm not sure allOf has anything to do with this issue. I think it's an issue of visibility of the rest of an included document when you're using a fragment identifier. It may be undefined behaviour as to whether internal $refs in the included document should be resolved and can 'see' properties outside of this fragment.
In my resolver (which is not the one used by ReDoc) it creates this issue:
#/paths/~1base/get/responses/200/content/application~1json/schema/allOf/1/properties/meta/$ref
Cannot resolve reference: #/components/schemas/Meta
This is because I'm trying to preserve internal $refs, not dereference every one. However, that $ref only has meaning inside that document... It's not possible to attach the referenced components.schemas content to the root OpenAPI object (it might use definitions instead of components.schemas for example), so rewriting the $refs is problematic. Resolving those internal $refs might be the only sensible approach.
The JSON-Reference spec seems woolly on this point, and helpfully, does not feature any examples. Do you have a particular reading of the spec?
MikeRalphson
on 24 Nov 2017
With everything resolved (it seems when you start resolving, it is dangerous to stop), I see this issue:
#/paths/~1me/get/responses/200/content/application~1json/allOf/1
Schema object cannot have additionalProperty: customer
from:
/me:
get:
tags:
- Me
summary: Summary of Me
responses:
'200':
description: OK
content:
application/json:
schema:
allOf:
- allOf:
- type: object
properties:
href:
type: string
- customer:
type: object
properties:
id:
type: integer
href:
type: string
This patch 'resolves' (ho-ho) it:
diff --git a/me/schemas.yaml b/me/schemas.yaml
index 9a9a9ad..7efb479 100644
--- a/me/schemas.yaml
+++ b/me/schemas.yaml
@@ -7,5 +7,5 @@ components:
MeOut:
allOf:
- $ref: '../schemas.yaml#/components/schemas/SelfHref'
- - $ref: '#/components/schemas/Me'
+ - $ref: '#/components/schemas/Me/customer'
@mikunn If you want to resolve/validate your OpenAPI 3.0 definitions as above, you can use swagger2openapi:
node testRunner -v -r swagger.yaml
or
node swagger2openapi -v -r swagger.yaml -o resolved.yaml
The online version at https://openapi-converter.herokuapp.com has also been updated to the latest version.
MikeRalphson
on 24 Nov 2017
@mikunn your case causes dereferencing issue in the ref parser I use. I've been able to simplify it a bit more but anyway it's really weird. I'll try to investigate it when I have spare time but can't promise it will be fixed quickly.
RomanHotsiy
on 24 Nov 2017
@RomanGotsiy you could always have a ReDoc option which uses swagger2openapi's resolver instead, just set options.resolve to true. You'd need ^2.11.5 as above.
MikeRalphson
on 24 Nov 2017
Thanks guys for the responses!
I've used json-refs to dereference which works well with that spec, but it still leaves some refs behind. json-schema-ref-parser or swagger2openapi should do the trick. Thanks for the example, @MikeRalphson :+1:.
No rush with the fix, I can do the extra dereferencing step until this is fixed :) The other issue that are already fixed were way more important!
I will try our other specs later and see how things work!
mikunn
on 24 Nov 2017
I got dereferencing working with json-schema-ref-parser. I tried swagger2openapi, but it left some $refs with full specs and ReDoc didn't like them.
I have another issue though. ReDoc seems to ignore parameters if it's on the same level as methods. E.g.
openapi: 3.0.0
info:
title: Test API
version: 0.1.0
paths:
'/test/{test_id}':
parameters:
- in: path
name: test_id
schema:
type: string
get:
tags:
- Test
summary: Test
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
properties:
foo:
type: string
If I move parameters inside get, it works just fine.
As a side note, if you forget the dash in parameters making it an object, ReDoc fails with (t.parameters || []).map is not a function. This is obviously a user fail but an easy one to make, so I thought to point it out if you want check that it's an array or something :)
This is starting to look really good. I'm running out of issues to report! :smiley:
mikunn
on 24 Nov 2017
@mikunn may not be related, but:
#/paths/~1test~1{test_id}/parameters/0
expected Object { in: 'path', name: 'test_id', schema: Object { type: 'string' } } to have property required
I tried swagger2openapi, but it left some $refs with full specs and ReDoc didn't like them.
If you have a testcase, please could you raise an issue over on swagger2openapi ? Thanks.
MikeRalphson
on 24 Nov 2017
@MikeRalphson Ah, I "optimized" a bit too much. It doesn't seem to be related.
If you have a testcase, please could you raise an issue over on swagger2openapi ? Thanks.
The spec is very complicated, but I'll see if I can reduce it to something sensible in a reasonable amount of time :)
mikunn
on 24 Nov 2017
Does it support Request/Response external examples yet?
I tried the standard Petstore example with an absolute url and a relative url to the json example files -
requestBody:
content:
'application/json':
schema:
$ref: '#/components/requestBodies/Pet'
examples:
catExample:
summary: This is a cat example in json
externalValue: 'https://raw.githubusercontent.com/suds123/ReDoc/gh-pages/cat.json'
dogExample:
summary: This is a dog example in json
externalValue: './dog.json'
But clicking on links does nothing...
Also no sure why I get a "null" at the end...
sudsk
on 24 Nov 2017
@MikeRalphson @RomanGotsiy - Hey guys, I am using create-react-app and the build is failing because of lib/jptr.js in reftools is using split ES6 function and create-react-app throws error when third-party packages don't compile their code to ES5 before publishing to npm.
let parts = prop.split('#')
Error:
Failed to minify the code from this file:
./node_modules/reftools/lib/jptr.js:40
Read more here: http://bit.ly/2tRViJ9
Any workaround or shall I open a ticket on reftools project?
j26nz
on 30 Nov 2017
Hi @j26nz thanks for reporting! What makes you think String.split() is an ES6 function, other than webpack/babel complaining about it? As far as I can see it has been present since 'ES1' ECMA-262.
It's almost certainly the use of let rather than var which is tripping things up, although from node 4 onwards this has been fine in modules with use strict; declarations.
There should be no requirement for npm modules to limit themselves to ES5 or suffer the lengthier build cycles or bloated packages. In my view it should be the responsibility of the consumer to specify the baseline requirements of their build (as only they know that) and transpile as necessary. swagger2openapi uses ES6 functions and let/const everywhere and the webpack/babel build of ReDoc cope just fine with that.
That said, reftools does seem to trip up webpack/babel/browserify and we're not 100% sure why that is.
So, if you were to open an issue on reftools, it would probably get closed as a 'wontfix', but if that package needs a webpack.config.js adding (and any devDependencies) then that would definitely be considered ok.
MikeRalphson
on 30 Nov 2017
@j26nz @MikeRalphson this is uglify.js issue which doesn't support es6 code yet (let, const)
But it will be fixed soon as webpack is upgrading to uglify-es: https://github.com/webpack-contrib/uglifyjs-webpack-plugin/pull/63, https://github.com/webpack/webpack/pull/5940
Anyway, I am transpiling reftools module and bundling it inside redoc.lib.js so this issue shouldn't happen.
I've tested it with create-react-app and it worked fine for me. Here is a sample repo: https://github.com/APIs-guru/create-react-app-redoc
@j26nz could you create an example repo with this issue? Thanks
RomanHotsiy
on 30 Nov 2017
@suds123 it doesn't support externalValue yet. It will be ready for the next alpha!
Thanks for the report!
RomanHotsiy
on 30 Nov 2017
@RomanGotsiy - thanks for confirming. I expected that.
Another question I have about support for multiple specs.
I used the same multiple specs example html as with 1.x.x. version. The initial Redoc.init works fine, but the onClick Redoc.init(url); doesn't do anything. Any idea how I can fix it or any workaround?
// initially render first API
Redoc.init(apis[0].url); // this works fine
function onClick() {
var url = this.getAttribute('data-link');
Redoc.init(url); // this doesn't do anything
}
@RomanGotsiy Highly appreciate that. I am running your example repo and it's throwing the same error on building. I ran on node 8.0 and 8.9.1 - still same issue. Wondering how is it working for you?
j26nz
on 30 Nov 2017
Works great with create-react-app and our existing definition. Looks like it's not responsive however, but maybe that's being worked on for an upcoming version?
Slettan
on 30 Nov 2017
@RomanGotsiy I am getting the same error as @j26nz with
https://github.com/APIs-guru/create-react-app-redoc
by running npm run build.
But regardless of the error the build folder gets created and everything seems to be working so far.
joskoanicic
on 1 Dec 2017
@mikunn @RomanGotsiy I encountered the refs issue too. Here is the smallest example to reproduce it https://github.com/ghola/redoc-refs-example . This was tested with 2.0.0-alpha4.
ghola
on 2 Dec 2017
@RomanGotsiy, I've run into an issue with the circular reference counting in a more complex document (resulting in infinite recursion). Haven't been able to put together a small reproducible test-case yet, but I was able to solve the problem -- looks like the ref counter decrements the ref even on an already-known circular reference. Patch here: https://gist.github.com/kroo/9a003d92762d2740bca56b52f2d4956c
kroo
on 4 Dec 2017
Hi, when import RedocStandalone in React i getting error on Firefox and Chrome. Same errors, but firefox show more logs.
Firefox: _TypeError: root is undefined
Note: two pictures because logs very large
Chrome: TypeError: Cannot set property 'Autolinker' of undefined
Version: 2.0.0-alpha.4
Occurs when add import: import {RedocStandalone} from 'redoc';
hugol1ma
on 5 Dec 2017
Hey here,
sorry for not responding. I've been on APITheDocs Amsterdam conference.
@j26nz, @joskoanicic thanks, I will try to investigate why the build errors for you.
@ghola, @kroo thanks! Will check it and let you know.
@hugol1ma could you share a minimally reproducible sample?
RomanHotsiy
on 6 Dec 2017
@RomanGotsiy code here: https://github.com/hugol1ma/simple-react-redoc
hugol1ma
on 6 Dec 2017
@hugol1ma sent a PR to your repo with the fix
@ghola @kroo @mikunn I think I found an issue and already sent a PR to json-schema-ref-parser. Once it is merged will let you know.
@j26nz, @joskoanicic should be fixed with the [email protected]
RomanHotsiy
on 7 Dec 2017
Thanks @RomanGotsiy! The dereference method of json-schema-ref-parserseems to work well, but obviously sticking with bundle would be better.
Any news on the path level parameter issue?
mikunn
on 7 Dec 2017
@RomanGotsiy thanks very much... I do not believe in my lack of attention. 😱. The real problem was the wrong reference of the node_modules folder on webpack.config.js
hugol1ma
on 7 Dec 2017
@kroo could you please share your spec or minimal reproducible sample? Because:
ref counter decrements the ref even on an already-known circular reference
is actually intentional so the issue is somewhere else. I'd like to investigate it.
RomanHotsiy
on 7 Dec 2017
@RomanGotsiy Any ETA on when might 2.0 might come out of alpha? Looks very promising..
shreyas-agnihotri
on 17 Dec 2017
Is there a place where you can download a build of the alpha version?
khamaileon
on 19 Dec 2017
@shreyas-agnihotri ETA is middle of Januray.
@khamaileon yes, check the details in the README: https://github.com/Rebilly/ReDoc/tree/react-rewrite#releases
Use next tag for the latest alpha, i.e.: https://unpkg.com/redoc@next/bundles/redoc.standalone.js
RomanHotsiy
on 19 Dec 2017
Not working in Safari & Firefox (see screenshot), works in Chrome
EDIT:
Note this only appears to happen when I include header markdown in my description in the definition document. For the time being I've omitted the h2 markdown and it behaves as expected now.
willvincent
on 19 Dec 2017
Bug: Schema titles not showing
Context
Schema titles are not displayed always. Instead the Schema IDs are shown.
[email protected]
Input
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/SchemaExample'
schemas:
SchemaExample:
type: object
properties:
query:
oneOf:
- $ref: '#/components/schemas/A_ID'
- $ref: '#/components/schemas/B_ID'
- $ref: '#/components/schemas/C_ID'
description: My description.
A_ID:
type: object
properties:
a_field:
type: number
format: float
title: A Title
B_ID:
type: string
title: B Title
C_ID:
type: array
items:
type: string
title: C Title
Result
Expected
- Instead of all the _A_ID_, _B_ID_ and _C_ID_, _A Title_, _B Title_ and _C Title_ should be displayed
Bonus
- The line: _A_ID (object) or B_ID (string) or string_, the later string should be actually [string]
- The _My description._ text should not be shown in the _One of_ box. I think this happens only with no structured schemas.
Great work! Thanks a lot for this tool!
enekid
on 20 Dec 2017
Bug: Default value not showing for Boolean fields
Context
When displaying a schema, the default values of boolean properties are not correctly shown.
true values -> empty box
false values -> nothing
[email protected]
Input
schemas:
SchemaExample:
type: object
properties:
booleanTrue:
type: boolean
description: a boolean:true
default: true
booleanFalse:
type: boolean
description: a boolean:false
default: false
Integer4:
type: integer
description: a integer:4
default: 4
Result
Expected
Default: true or Default: false
The automatically generated payload tab does it correctly:
enekid
on 22 Dec 2017
Any plans on supporting callbacks?
mikunn
on 23 Dec 2017
Required is not respected when using with discriminator schema
schema:
allOf:
- $ref: '#/components/schemas/Pet'
- required:
- name
Pet:
type: object
required:
- name
- photoUrls
discriminator:
propertyName: petType
mapping:
cat: '#/components/schemas/Cat'
dog: '#/components/schemas/Dog'
bee: '#/components/schemas/HoneyBee'
properties:
id:
description: Pet ID
allOf:
- $ref: '#/components/schemas/Id'
category:
description: Categories this pet belongs to
allOf:
- $ref: '#/components/schemas/Category'
name:
description: The name given to a pet
type: string
example: Guru
photoUrls:
description: The list of URL to a cute photos featuring pet
type: array
xml:
name: photoUrl
wrapped: true
items:
type: string
format: url
friend:
allOf:
- $ref: '#/components/schemas/Pet'
tags:
description: Tags attached to the pet
type: array
xml:
name: tag
wrapped: true
items:
$ref: '#/components/schemas/Tag'
status:
type: string
description: Pet status in the store
enum:
- available
- pending
- sold
petType:
description: Type of a pet
type: string
xml:
name: Pet
ahshum
on 3 Jan 2018
Header component is not respected properly
path:
/pet:
post:
...
responses:
200:
headers:
'Header-One':
$ref: '#/components/headers/HeaderOne'
...
components:
headers:
HeaderOne:
description: Header one
schema:
type: integer
Reference object should be extensible. Currently, only #/components/schemas/ works as expected.
example for #/components/responses
path:
/pet:
post:
...
responses:
200:
allOf:
- $ref: '#/components/responses/ResponseOne'
- content:
application/json:
schema:
type: string
...
components:
headers:
HeaderOne:
description: Header one
schema:
type: integer
responses:
ResponseOne:
headers:
'Header-One':
$ref: '#/components/headers/HeaderOne'
Reference object should be extensible
@aHxShUM the allOf wrapping a $ref and other schemas is only valid within a Schema Object, not a Response Object, as you have in your example.
MikeRalphson
on 10 Jan 2018
Are "copy to clipboard" and "expand/collapse all" implemented yet for response samples? Is it on the roadmap?
joshprice
on 19 Jan 2018
Also found that h2 headings (specifically without any h1s) in the description markdown throw an error:
info:
description: "
## Introduction
"
Throws:
Cannot read property 'items' of undefined
Stack trace
TypeError: Cannot read property 'items' of undefined
at Object.MarkdownRenderer.headingOpenRule [as heading_open] (http://localhost:3000/static/js/bundle.js:87509:81)
at Renderer../node_modules/remarkable/lib/renderer.js.Renderer.render (http://localhost:3000/static/js/bundle.js:99916:39)
at Remarkable../node_modules/remarkable/lib/index.js.Remarkable.render (http://localhost:3000/static/js/bundle.js:99376:24)
at MarkdownRenderer../src/services/MarkdownRenderer.ts.MarkdownRenderer.renderMd (http://localhost:3000/static/js/bundle.js:87577:22)
at MarkdownRenderer../src/services/MarkdownRenderer.ts.MarkdownRenderer.extractHeadings (http://localhost:3000/static/js/bundle.js:87585:14)
at Function../src/services/MenuBuilder.ts.MenuBuilder.addMarkdownItems (http://localhost:3000/static/js/bundle.js:87681:33)
at Function../src/services/MenuBuilder.ts.MenuBuilder.buildStructure (http://localhost:3000/static/js/bundle.js:87666:45)
at SpecStore.get (http://localhost:3000/static/js/bundle.js:88532:86)
at trackDerivedFunction (http://localhost:3000/static/js/bundle.js:37726:20)
at ComputedValue../node_modules/mobx/lib/mobx.module.js.ComputedValue.computeValue (http://localhost:3000/static/js/bundle.js:36265:19)
at ComputedValue../node_modules/mobx/lib/mobx.module.js.ComputedValue.trackAndCompute (http://localhost:3000/static/js/bundle.js:36254:43)
at ComputedValue../node_modules/mobx/lib/mobx.module.js.ComputedValue.get (http://localhost:3000/static/js/bundle.js:36214:26)
at SpecStore.<anonymous> (http://localhost:3000/static/js/bundle.js:38039:27)
at SpecStore.get (http://localhost:3000/static/js/bundle.js:35857:32)
at MenuStore.get (http://localhost:3000/static/js/bundle.js:87860:41)
at ComputedValue../node_modules/mobx/lib/mobx.module.js.ComputedValue.computeValue (http://localhost:3000/static/js/bundle.js:36269:39)
at ComputedValue../node_modules/mobx/lib/mobx.module.js.ComputedValue.get (http://localhost:3000/static/js/bundle.js:36208:35)
at MenuStore.<anonymous> (http://localhost:3000/static/js/bundle.js:38039:27)
at MenuStore.get (http://localhost:3000/static/js/bundle.js:35857:32)
at Redoc../src/components/Redoc/Redoc.tsx.Redoc.render (http://localhost:3000/static/js/bundle.js:85408:174)
at finishClassComponent (http://localhost:3000/static/js/bundle.js:57236:31)
at updateClassComponent (http://localhost:3000/static/js/bundle.js:57213:12)
at beginWork (http://localhost:3000/static/js/bundle.js:57588:16)
at performUnitOfWork (http://localhost:3000/static/js/bundle.js:59587:16)
at workLoop (http://localhost:3000/static/js/bundle.js:59651:26)
at HTMLUnknownElement.callCallback (http://localhost:3000/static/js/bundle.js:49905:14)
at Object.invokeGuardedCallbackDev (http://localhost:3000/static/js/bundle.js:49944:16)
at invokeGuardedCallback (http://localhost:3000/static/js/bundle.js:49801:27)
at renderRoot (http://localhost:3000/static/js/bundle.js:59729:7)
at performWorkOnRoot (http://localhost:3000/static/js/bundle.js:60377:24)
at performWork (http://localhost:3000/static/js/bundle.js:60330:7)
at requestWork (http://localhost:3000/static/js/bundle.js:60241:7)
at scheduleWorkImpl (http://localhost:3000/static/js/bundle.js:60095:11)
at scheduleWork (http://localhost:3000/static/js/bundle.js:60052:12)
at Object.enqueueSetState (http://localhost:3000/static/js/bundle.js:55575:7)
at StoreProvider../node_modules/react/cjs/react.development.js.Component.setState (http://localhost:3000/static/js/bundle.js:75067:16)
at StoreProvider.<anonymous> (http://localhost:3000/static/js/bundle.js:87040:30)
at step (http://localhost:3000/static/js/bundle.js:87004:23)
at Object.next (http://localhost:3000/static/js/bundle.js:86985:53)
at fulfilled (http://localhost:3000/static/js/bundle.js:86976:58)
at <anonymous>
ReDoc Version: 2.0.0-alpha.9
Commit: 392ac71
Looks like this line is the culprit https://github.com/Rebilly/ReDoc/blob/react-rewrite/src/services/MarkdownRenderer.ts#L97
Couldn't find any tests for that file though.
joshprice
on 19 Jan 2018
My Open API 3.0 specifications renders on alpha.5 or earlier (you can see it and download spec here), but every newer version up to the latest alpha.10 causes an error:
Something went wrong...
t.schema is undefined
Stack trace
./src/standalone.tsx/ca</t.prototype.render@https://unpkg.com/[email protected]/bundles/redoc.standalone.js:75:244032
S@https://unpkg.com/[email protected]/bundles/redoc.standalone.js:27:75676
u/<@https://unpkg.com/[email protected]/bundles/redoc.standalone.js:75:168036
ut@https://unpkg.com/[email protected]/bundles/redoc.standalone.js:27:90265
./node_modules/mobx/lib/mobx.module.js/</$n</e.prototype.track@https://unpkg.com/[email protected]/bundles/redoc.standalone.js:41:27171
u@https://unpkg.com/[email protected]/bundles/redoc.standalone.js:75:167974
c@https://unpkg.com/[email protected]/bundles/redoc.standalone.js:75:167926
l@https://unpkg.com/[email protected]/bundles/redoc.standalone.js:52:134816
beginWork@https://unpkg.com/[email protected]/bundles/redoc.standalone.js:52:136536
o@https://unpkg.com/[email protected]/bundles/redoc.standalone.js:52:148657
s@https://unpkg.com/[email protected]/bundles/redoc.standalone.js:52:148978
a@https://unpkg.com/[email protected]/bundles/redoc.standalone.js:52:149216
j@https://unpkg.com/[email protected]/bundles/redoc.standalone.js:52:152759
_@https://unpkg.com/[email protected]/bundles/redoc.standalone.js:52:152496
h@https://unpkg.com/[email protected]/bundles/redoc.standalone.js:52:151624
f@https://unpkg.com/[email protected]/bundles/redoc.standalone.js:52:151014
enqueueSetState@https://unpkg.com/[email protected]/bundles/redoc.standalone.js:52:125595
./node_modules/react/cjs/react.production.min.js/o.prototype.setState@https://unpkg.com/[email protected]/bundles/redoc.standalone.js:68:670
./src/standalone.tsx/Ht</t.prototype.load/</<@https://unpkg.com/[email protected]/bundles/redoc.standalone.js:75:161716
r@https://unpkg.com/[email protected]/bundles/redoc.standalone.js:75:160944
n/<@https://unpkg.com/[email protected]/bundles/redoc.standalone.js:75:160281
s@https://unpkg.com/[email protected]/bundles/redoc.standalone.js:75:160020
T/</<@https://unpkg.com/[email protected]/bundles/redoc.standalone.js:15:39324
T/<@https://unpkg.com/[email protected]/bundles/redoc.standalone.js:15:39194
c@https://unpkg.com/[email protected]/bundles/redoc.standalone.js:15:21273
ReDoc Version: 2.0.0-alpha.10
Commit: 8df469f
adrianz
on 19 Jan 2018
Thanks everyone for issue reports. I will be tackling them next days and will update you.
Are "copy to clipboard" and "expand/collapse all" implemented yet for response samples? Is it on the roadmap?
@joshprice, Yes, I just have to port this functionality. I created an issue if anyone wants to help with that: https://github.com/Rebilly/ReDoc/issues/410
Any plans on supporting callbacks?
@mikunn yes. It is planned. I don't have any ideas on how to visualize those. Let's discuss it in separate issue: https://github.com/Rebilly/ReDoc/issues/411
@adrianz could you share a minimal reproducible sample?
RomanHotsiy
on 21 Jan 2018
api.yml
```swagger: '2.0'
info:
version: '1.0'
title: Demo API
paths:
/health/all.json:
get:
responses:
200:
description: OK
schema:
$ref: definitions/health.yml#/Result
definitions/health.yml
Check:
title: Check
type: object
properties:
message:
type: string
description: "bla"
Result:
type: object
properties:
default:
$ref: '#/Check'
database:
$ref: '#/Check'
```
I dunno whats going on but this is a tiny version of the schema that breaks. Struggled to isolate it exactly.
philsturgeon
on 23 Jan 2018
@philsturgeon it's caused by bundling and conversion issue of your openapi 2 to openapi 3 (opened issue https://github.com/Mermade/swagger2openapi/issues/51 cc @MikeRalphson)
I'll try to figure it out asap as this seems to be really critical.
RomanHotsiy
on 24 Jan 2018
@RomanGotsiy the fix for rewriting direct $refs is in swagger2openapi v2.11.11
MikeRalphson
on 25 Jan 2018
And hardened slightly in v2.11.12
MikeRalphson
on 25 Jan 2018
Ok! The fixes to swagger2openapi have fixed a few of my errors, and bad specs were the cause of a few others, but the saga continues.
Markdown headers in the info.description triggers an error:
{
"openapi": "3.0.0",
"info": {
"version": "1.0",
"title": "Foo",
"description": "Text.\n\n## Header"
},
"paths": {
"/": {
"get": {
}
}
}
}
Error looks like this:
e.currentTopHeading is undefined
Stack trace
e/this.headingOpenRule@https://unpkg.com/[email protected]/bundles/redoc.standalone.js:75:133960
./node_modules/remarkable/lib/renderer.js/r.prototype.render@https://unpkg.com/[email protected]/bundles/redoc.standalone.js:68:70741
./node_modules/remarkable/lib/index.js/o.prototype.render@https://unpkg.com/[email protected]/bundles/redoc.standalone.js:68:64587
./src/standalone.tsx/Ve</e.prototype.renderMd@https://unpkg.com/[email protected]/bundles/redoc.standalone.js:75:135395
./src/standalone.tsx/Ve</e.prototype.extractHeadings@https://unpkg.com/[email protected]/bundles/redoc.standalone.js:75:135515
./src/standalone.tsx/Ze</e.addMarkdownItems@https://unpkg.com/[email protected]/bundles/redoc.standalone.js:75:136546
./src/standalone.tsx/Ze</e.buildStructure@https://unpkg.com/[email protected]/bundles/redoc.standalone.js:75:136325
get@https://unpkg.com/[email protected]/bundles/redoc.standalone.js:75:142825
ut@https://unpkg.com/[email protected]/bundles/redoc.standalone.js:27:90265
./node_modules/mobx/lib/mobx.module.js/</gn</e.prototype.computeValue@https://unpkg.com/[email protected]/bundles/redoc.standalone.js:41:18139
./node_modules/mobx/lib/mobx.module.js/</gn</e.prototype.trackAndCompute@https://unpkg.com/[email protected]/bundles/redoc.standalone.js:41:17982
./node_modules/mobx/lib/mobx.module.js/</gn</e.prototype.get@https://unpkg.com/[email protected]/bundles/redoc.standalone.js:41:17207
Ot/<@https://unpkg.com/[email protected]/bundles/redoc.standalone.js:27:92692
get@https://unpkg.com/[email protected]/bundles/redoc.standalone.js:27:76302
get@https://unpkg.com/[email protected]/bundles/redoc.standalone.js:75:130803
./node_modules/mobx/lib/mobx.module.js/</gn</e.prototype.computeValue@https://unpkg.com/[email protected]/bundles/redoc.standalone.js:41:18186
./node_modules/mobx/lib/mobx.module.js/</gn</e.prototype.get@https://unpkg.com/[email protected]/bundles/redoc.standalone.js:41:17158
Ot/<@https://unpkg.com/[email protected]/bundles/redoc.standalone.js:27:92692
get@https://unpkg.com/[email protected]/bundles/redoc.standalone.js:27:76302
./src/standalone.tsx/Gl</t.prototype.render@https://unpkg.com/[email protected]/bundles/redoc.standalone.js:75:280508
l@https://unpkg.com/[email protected]/bundles/redoc.standalone.js:52:134816
beginWork@https://unpkg.com/[email protected]/bundles/redoc.standalone.js:52:136536
o@https://unpkg.com/[email protected]/bundles/redoc.standalone.js:52:148657
s@https://unpkg.com/[email protected]/bundles/redoc.standalone.js:52:148978
a@https://unpkg.com/[email protected]/bundles/redoc.standalone.js:52:149216
j@https://unpkg.com/[email protected]/bundles/redoc.standalone.js:52:152759
_@https://unpkg.com/[email protected]/bundles/redoc.standalone.js:52:152496
h@https://unpkg.com/[email protected]/bundles/redoc.standalone.js:52:151624
f@https://unpkg.com/[email protected]/bundles/redoc.standalone.js:52:151014
enqueueSetState@https://unpkg.com/[email protected]/bundles/redoc.standalone.js:52:125595
./node_modules/react/cjs/react.production.min.js/o.prototype.setState@https://unpkg.com/[email protected]/bundles/redoc.standalone.js:68:670
./src/standalone.tsx/Ht</t.prototype.load/</<@https://unpkg.com/[email protected]/bundles/redoc.standalone.js:75:161716
r@https://unpkg.com/[email protected]/bundles/redoc.standalone.js:75:160944
n/<@https://unpkg.com/[email protected]/bundles/redoc.standalone.js:75:160281
s@https://unpkg.com/[email protected]/bundles/redoc.standalone.js:75:160020
T/</<@https://unpkg.com/[email protected]/bundles/redoc.standalone.js:15:39324
T/<@https://unpkg.com/[email protected]/bundles/redoc.standalone.js:15:39194
c@https://unpkg.com/[email protected]/bundles/redoc.standalone.js:15:21273
default: false is not showing in the schema of requestBody and responses
requestBody:
content:
application/json:
schema:
type: object
properties:
attr:
type: boolean
default: false
responses:
200:
content:
application/json:
schema:
type: object
properties:
attr:
type: boolean
default: false
@philsturgeon that looks like the same headings error I was getting in https://github.com/Rebilly/ReDoc/issues/384#issuecomment-358832228
If you start with h1 then it should work. Is it worth raising a separate top level issue for this?
joshprice
on 28 Jan 2018
alpha.11 has just been released!
Changelog here:
https://github.com/Rebilly/ReDoc/blob/react-rewrite/CHANGELOG.md#200-alpha11-2018-01-29
RomanHotsiy
on 29 Jan 2018
Error in oneOf selector in alpha11: click to one of buttons throws Uncaught TypeError: Cannot read property 'props' of undefined at t.activateOneOf (OneOfSchema.tsx:28)
Alpha10 works fine.
mevl
on 30 Jan 2018
Incorrect type rendered in oneOf selector, "array" type rendered as "object".
Expected one button is "object" and another is "array" or better - "array of object", but both rendered as "object".
Below a small part of OAS3:
"relationshipData": {
"oneOf": [
{"$ref": "#/components/x-jsonapi/relationshipOne"},
{"$ref": "#/components/x-jsonapi/relationshipMany"}
],
},
"relationshipMany": {
"type": "array",
"items": {
"$ref": "#/components/x-jsonapi/linkage", // this is a object
},
"uniqueItems": true
},
"relationshipOne": {
"$ref": "#/components/x-jsonapi/linkage" // this is a object
}
Latest release alpha.11 fixes the issues I reported (Thanks! ❤️ ) but noticed a couple more:
- Delete verb styles appear to be pulling in some old sass from
mixins.sassand.deletestyle applies and adds anXand sizing that breaks things visually. I couldn't figure out how this was being pulled in, but presumably since you're using styled components, the old sass is redundant. - Expanding some response schemas throws an error when expanding some elements with nested discriminators:
TypeError: Cannot read property 'fields' of undefined
at ObjectSchema../src/components/Schema/ObjectSchema.tsx.ObjectSchema.render (http://localhost:3000/static/js/bundle.js:96249:45)
Tracked the error down to a missing schema prop here, but haven't figured out what triggers it:
https://github.com/Rebilly/ReDoc/blob/react-rewrite/src/components/Schema/ObjectSchema.tsx#L68
Reproducible with a minimal spec:
swagger: '2.0'
info:
title: "Broken Redoc Discriminator"
paths:
'/foo':
get:
responses:
200:
schema:
$ref: '#/definitions/FooTopLevel'
definitions:
JsonApiResource:
type: object
description: A related resource.
required:
- type
discriminator: type
properties:
type:
type: string
description: The type of object this resource represents.
FooTopLevel:
type: object
required:
- data
properties:
data:
$ref: '#/definitions/Foo'
Foo:
allOf:
- type: object
- $ref: '#/definitions/JsonApiResource'
Error is not encountered if discriminator: type is removed or commented in JsonApiResource.
joshprice
on 31 Jan 2018
Got a few more!
1.
o is undefined
Stack trace
e/this.schemes<@https://unpkg.com/[email protected]/bundles/redoc.standalone.js:80:19389
e@https://unpkg.com/[email protected]/bundles/redoc.standalone.js:80:19294
e/this.security<@https://unpkg.com/[email protected]/bundles/redoc.standalone.js:80:28162
e@https://unpkg.com/[email protected]/bundles/redoc.standalone.js:80:28106
./src/standalone.tsx/Qt</e.getOperationsItems@https://unpkg.com/[email protected]/bundles/redoc.standalone.js:80:32783
./src/standalone.tsx/Qt</e.getTagsItems@https://unpkg.com/[email protected]/bundles/redoc.standalone.js:80:32491
./src/standalone.tsx/Qt</e.buildStructure@https://unpkg.com/[email protected]/bundles/redoc.standalone.js:80:31895
get@https://unpkg.com/[email protected]/bundles/redoc.standalone.js:80:17686
ut@https://unpkg.com/[email protected]/bundles/redoc.standalone.js:27:90583
./node_modules/mobx/lib/mobx.module.js/</bn</e.prototype.computeValue@https://unpkg.com/[email protected]/bundles/redoc.standalone.js:41:18139
./node_modules/mobx/lib/mobx.module.js/</bn</e.prototype.trackAndCompute@https://unpkg.com/[email protected]/bundles/redoc.standalone.js:41:17982
./node_modules/mobx/lib/mobx.module.js/</bn</e.prototype.get@https://unpkg.com/[email protected]/bundles/redoc.standalone.js:41:17207
Ot/<@https://unpkg.com/[email protected]/bundles/redoc.standalone.js:27:93010
get@https://unpkg.com/[email protected]/bundles/redoc.standalone.js:27:76620
get@https://unpkg.com/[email protected]/bundles/redoc.standalone.js:80:34010
./node_modules/mobx/lib/mobx.module.js/</bn</e.prototype.computeValue@https://unpkg.com/[email protected]/bundles/redoc.standalone.js:41:18186
./node_modules/mobx/lib/mobx.module.js/</bn</e.prototype.get@https://unpkg.com/[email protected]/bundles/redoc.standalone.js:41:17158
Ot/<@https://unpkg.com/[email protected]/bundles/redoc.standalone.js:27:93010
get@https://unpkg.com/[email protected]/bundles/redoc.standalone.js:27:76620
-
2.
Something went wrong...
e.replace is not a function
Stack trace
./node_modules/remarkable/lib/parser_block.js/r.prototype.parse@https://unpkg.com/[email protected]/bundles/redoc.standalone.js:68:66841
./node_modules/remarkable/lib/rules_core/block.js/e.exports@https://unpkg.com/[email protected]/bundles/redoc.standalone.js:68:94098
./node_modules/remarkable/lib/parser_core.js/r.prototype.process@https://unpkg.com/[email protected]/bundles/redoc.standalone.js:68:68058
./node_modules/remarkable/lib/index.js/o.prototype.parse@https://unpkg.com/[email protected]/bundles/redoc.standalone.js:68:64558
./node_modules/remarkable/lib/index.js/o.prototype.render@https://unpkg.com/[email protected]/bundles/redoc.standalone.js:68:64658
./src/standalone.tsx/Kt</e.prototype.renderMd@https://unpkg.com/[email protected]/bundles/redoc.standalone.js:80:30815
./src/standalone.tsx/zi</t.prototype.render@https://unpkg.com/[email protected]/bundles/redoc.standalone.js:80:84277
l@https://unpkg.com/[email protected]/bundles/redoc.standalone.js:52:101359
beginWork@https://unpkg.com/[email protected]/bundles/redoc.standalone.js:52:103079
o@https://unpkg.com/[email protected]/bundles/redoc.standalone.js:52:115200
s@https://unpkg.com/[email protected]/bundles/redoc.standalone.js:52:115521
a@https://unpkg.com/[email protected]/bundles/redoc.standalone.js:52:115759
w@https://unpkg.com/[email protected]/bundles/redoc.standalone.js:52:119302
_@https://unpkg.com/[email protected]/bundles/redoc.standalone.js:52:119039
h@https://unpkg.com/[email protected]/bundles/redoc.standalone.js:52:118167
f@https://unpkg.com/[email protected]/bundles/redoc.standalone.js:52:117557
and finally 3.
quite impressive that one!
I sent you the spec file for 3 on slack. :)
philsturgeon
on 31 Jan 2018
Just cut alpha.12
@mevl your both issues should be fixed
@joshprice your second issue should be fixed. Have no idea about the first one
@philsturgeon your issues should be fixed now too
🎉
Also:
- added basic responsiveness
- started working on search locally... very close to the first RC
RomanHotsiy
on 8 Feb 2018
@RomanGotsiy thank you, alpha.12 fixes the issues I reported, but oneOf active button isn't correctly highlighted now.
And I found one more issue:
Header object name in #/components/headers definition must not be specified (OAS3 spec.):
The Header Object follows the structure of the Parameter Object with the following changes:
- name MUST NOT be specified, it is given in the corresponding headers map.
...
but it is not given, empty header name is rendered.
{
"components": {
"headers": {
"contentLanguage": { // name MUST NOT be specified
"description": "The response content language",
"schema": {
"type": "string",
}
}
},
"responses": {
"success": {
"description": "Success response sample",
"headers": {
"Content-Language": {
"$ref": "#/components/headers/contentLanguage" // will be renedered with empty name
}
}.
...
}
}
}
}
I'm not sure this issue is strictly a 2.0.0 issue, but here goes...
I inherited an API with a rough input structure. Essentially, I have a transactions endpoint that allows 3 formats of payment method input (ID, Token, Account) and 6 types of transactions (Auth, Capture, Sale, Refund, Credit, Void).
Individually and with other endpoints, the discriminators for payment method and transactions behave as expected.
Here's the smallest chunk of my OAS yaml that can get the point across:
PaymentsOrder:
description: The base order model for transaction.
type: object
required:
- Type
properties:
Type:
description: Not required. Inferred from request body.
type: string
discriminator:
propertyName: Type
mapping:
Sale: '#/components/schemas/PaymentsOrderSale'
Auth: '#/components/schemas/PaymentsOrderAuth'
Capture: '#/components/schemas/PaymentsOrderCapture'
Refund: '#/components/schemas/PaymentsOrderRefund'
Credit: '#/components/schemas/PaymentsOrderCredit'
Void: '#/components/schemas/PaymentsOrderVoid'
PaymentsOrderSale:
allOf:
- $ref: '#/components/schemas/PaymentsOrder'
- $ref: '#/components/schemas/PaymentMethodRequest'
- type: object
required:
- Transaction
properties:
Customer:
type: integer
description:
Used to associate with an existing customer. If included, must be an integer.
Validation occurs when using payment method ID.
example: 7313
SavePaymentMethod:
$ref: '#/components/schemas/SavePaymentMethod'
Transaction:
$ref: '#/components/schemas/TransactionRequestSale'
PaymentMethodRequest:
description: The payment method object.
type: object
required:
- PaymentMethod
properties:
PaymentMethod:
type: string
description: Not required. Inferred from request body.
enum:
- ID
- Token
- Account
discriminator:
propertyName: PaymentMethod
mapping:
ID: '#/components/schemas/PaymentMethodRequestByID'
Token: '#/components/schemas/PaymentMethodRequestByToken'
Account: '#/components/schemas/PaymentMethodRequestByAccount'
You can see in the PaymentsOrder schema that I'm using allOf to represent the field collections. It has its own discriminator, but so does the PaymentMethodRequest schema. When it renders, only the main schema's discriminator is rendered:
DISCLAIMER: I know that this API is not ideal for OAS 3.0.0. The fact that the payment method fields are "flat" inside of the PaymentsOrder object is the root cause. Also, if this question is too broad for the 2.0.0 issues thread, I can delete and move it to its own issue.
QUESTIONS:
- There's nothing in the OAS 3.0.0 specification that explicitly says multiple discriminators shouldn't work. From a theory perspective, _is it unreasonable to think this could work some day?_
- Though I'm sure it's the ideal solution -- but since this is a legacy API, I can not reasonably change the actual API behavior -- _is there another way to document this without moving the PaymentMethod schema into its own sub-schema of PaymentsOrder?_ The only thing that comes to mind is creating a PaymentsOrder schema for each allowed combination of PaymentMethod and Type.
UPDATE -- I resolved my issue by mapping the combinations into separate PaymentsOrder schemas. It has worked well. This ticket can be deleted if it is deemed to be not constructive.
trip-somers
on 13 Feb 2018
I'm back with an actual 2.0.0-alpha.12 issue.
DESCRIPTION:
I have a discriminator selector box that exhibits the following behavior:
- Loads with first mapping selected, shows wrong fields.
- On first selection of an option: the correct fields show up, but the selector "jumps" 2 options down. For example, if I select the first option, its fields will be displayed, but the selector will show that I selected the third option. (And if I select my last option, the second option shows as selected.)
- If I re-select the intended option, the selector shows the correct option. The correct fields remain.
This schema is used in multiple places in my documentation, and it behaves the same for all instances, at least one of which is nested inside of another rendered discriminator.
Here are the relevant schemas:
Account:
type: object
description: An Account
required:
- Type
properties:
Type:
type: string
enum:
- visa
- mastercard
- amex
- discover
- checking
- savings
discriminator:
propertyName: Type
mapping:
visa: '#/components/schemas/AccountCreditCardVisa'
mastercard: '#/components/schemas/AccountCreditCardMasterCard'
amex: '#/components/schemas/AccountCreditCardAmex'
discover: '#/components/schemas/AccountCreditCardDiscover'
checking: '#/components/schemas/AccountBankAccountChecking'
savings: '#/components/schemas/AccountBankAccountSavings'
AccountBankAccount:
type: object
required:
- Number
- RoutingNumber
properties:
Number:
type: string
description: The full account number of the bank account.
RoutingNumber:
type: string
description: The full routing number of the bank.
AccountBankAccountChecking:
allOf:
- $ref: '#/components/schemas/Account'
- $ref: '#/components/schemas/AccountBankAccount'
AccountBankAccountSavings:
allOf:
- $ref: '#/components/schemas/Account'
- $ref: '#/components/schemas/AccountBankAccount'
AccountCreditCard:
type: object
required:
- Number
- Cvv2
- ExpireDate
properties:
Number:
type: string
description: The credit card account number.
Cvv2:
type: string
description: The credit card security code.
ExpireDate:
type: string
format: MMYY
description: The credit card expiration date.
AccountCreditCardVisa:
allOf:
- $ref: '#/components/schemas/Account'
- $ref: '#/components/schemas/AccountCreditCard'
AccountCreditCardMasterCard:
allOf:
- $ref: '#/components/schemas/Account'
- $ref: '#/components/schemas/AccountCreditCard'
AccountCreditCardAmex:
allOf:
- $ref: '#/components/schemas/Account'
- $ref: '#/components/schemas/AccountCreditCard'
AccountCreditCardDiscover:
allOf:
- $ref: '#/components/schemas/Account'
- $ref: '#/components/schemas/AccountCreditCard'
Here is the requestBody in which it is used most simply:
requestBody:
description: Request body needed to create a payment method token
required: true
content:
application/json:
schema:
type: object
required:
- Order
properties:
Order:
type: object
required:
- Account
- AccountHolder
properties:
Customer:
type: integer
description: |
The ID of the customer to which the payment method
should be attached. If omitted, a new customer will be
created.
example: 7313
Account:
$ref: '#/components/schemas/Account'
AccountHolder:
$ref: '#/components/schemas/AccountHolder'
When the Account schema is rendered, 'visa' is selected as the first option, but the BankAccount fields are shown. When I select 'discover', the credit card fields are shown but 'savings' winds up selected. When I click 'discover' again, the credit card fields remain, and 'discover' is selected.
The images below show (1) before selecting 'discover' the first time and (2) the result of first click of 'discover'.
Is there something wrong with my schemas, or is this a rendering issue in 2.0.0-alpha.12?
trip-somers
on 14 Feb 2018
I have two cosmetic issues, one related to the rendition of oneOf and the second to the rendition of examples.
When you have a schema which makes use of oneOf (without any discriminator), the rendition looks like this:
When you click on one of those object buttons, they do not get highlighted, although the content underneath them does change. So I guess that there are two problems here:
- Not highlighing the currently active object
- Is there a way to not have it display
objectand use a more descriptive text?
When you have mutiple examples, they do not get formatted according to the content type. In the below image you can see that it's application/json yet the rendition is not pretty printed:
ghola
on 16 Feb 2018
Seems "response samples" section does not respect openapi 3.0 writeOnly attribute. Attribute "only_write" is not shown in "reponses" section but is shown in samples when using this minimalistic example:
openapi: 3.0.0
info:
version: 1.0.0
title: test
paths:
/test:
get:
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/test_object'
responses:
200:
description: ok
content:
application/json:
schema:
$ref: '#/components/schemas/test_object'
components:
schemas:
test_object:
type: object
properties:
only_write:
type: string
writeOnly: true
read_write:
type: string
readOnly is working as expected also in samples section.
misos1
on 19 Feb 2018
BUG:
Not sure if this was mentioned somewhere above, but a really long JSON doesn't fit in the response area.
theholiday
on 20 Feb 2018
BUG:
Seems readOnly and writeOnly are not respected in objects under oneOf or anyOf. In request section should not be only_read parameter and in response should not be only_write. Exception is request sample where is only_read parameter correctly hidden.
components:
schemas:
test_object:
oneOf:
- $ref: '#/components/schemas/Cat'
- $ref: '#/components/schemas/Dog'
Cat:
type: object
properties:
read_write:
type: string
only_read:
type: string
readOnly: true
only_write:
type: string
writeOnly: true
Dog:
type: object
properties:
name:
type: string
misos1
on 20 Feb 2018
Also regarding previous comment, when I click on Dog then I would expect that Dog button will become blue with white text and Cat white with blue text but this is not happening.
misos1
on 20 Feb 2018
Seems openapi 3.0.0 links https://swagger.io/docs/specification/links/ are not implemented, they are not shown nowhere.
misos1
on 20 Feb 2018
BUG:
allOf does not merge nested properties of properties with same name. Specification https://swagger.io/docs/specification/data-models/oneof-anyof-allof-not/ is saying "allOf – validates the value against all the subschemas". There should be "nested_1" property inside property "prop"
components:
schemas:
test_object:
allOf:
- type: object
properties:
prop:
type: object
properties:
nested_1:
type: string
- type: object
properties:
prop:
type: object
properties:
nested_2:
type: string
Swagger editor is showing them both:
misos1
on 20 Feb 2018
This is really subtle but selecting menu items during scrolling could be triggered sooner. On first image I scrolled close to second item but still is selected first menu item in left top. On second image I scrolled little down so top horizontal line is above top edge and now is selected second item. Maybe would be better looking when are menu items selected as soon as that horizontal line goes through screen center in some point as is shown on third picture. Of course when clicking on menu items it is good as it is now that summary of selected item is scrolled to top.
misos1
on 20 Feb 2018
BUG:
Property attributes readOnly and writeOnly are not respected when specified in object inside array (except in request samples).
test_object:
type: object
properties:
array:
type: array
items:
type: object
properties:
only_read:
type: string
readOnly: true
only_write:
type: string
writeOnly: true
read_write:
type: string
misos1
on 22 Feb 2018
This looks like a new one for alpha12, but maybe I don't understand the OAS 3.0.0 docs.
example definitions from components.headers do not render in request output. Yes, that sounds weird, but I'm using $ref to pull some header schemas into a few JSON bodies that feature 'Header' and 'Body' elements. The examples render for 'Body', but 'Header' just shows null for everything.
Here is a brief example of how the 'Header' element is being populated in my spec:
components:
headers:
Application:
description: Always "PaymentSystem".
schema:
type: string
enum:
- PaymentSystem
example: PaymentSystem
schemas:
RequestHeaders:
type: object
description: Request headers to be included on all requests.
required:
- Application
- Mode
- Security
properties:
Application:
$ref: '#/components/headers/Application'
And here is how I reference it in a path's operation's requestBody:
requestBody:
description: Request body needed to retrieve a merchant's rates
content:
application/json:
schema:
type: object
required:
- Header
- Body
properties:
Header:
$ref: '#/components/schemas/RequestHeaders'
Body:
type: object
enum:
- null
Are there plans to render the request examples based on discriminator selection?
You can see in my example just above this that the only field that shows up for 'Account' is 'Type' (my discriminator) and none of the other fields (spec not shown but those fields include: Number, ExpirationDate, and Cvv2).
trip-somers
on 9 Mar 2018
Running [email protected] but didn't manage to get scrollYOffset to work. Is this correct?
options={{
scrollYOffset: 72,
}}
magnusros
on 13 Mar 2018
Hey everyone,
I release a new alpha with most the issues fixed since the previous alpha. I can't answer to everyone so please check the latest alpha and if your issue is not fixed, let me know.
https://twitter.com/RomanHotsiy/status/974381615135719426
@misos1 links are not yet implemented. Track here https://github.com/Rebilly/ReDoc/issues/437
@trip-somers multiple discriminators are not working yet. Regarding your last issue. You should reference schema not parameter: $ref: '#/components/schemas/RequestHeaders/schema' (notice schema in the end)
@magnusros yes, this seems to be correct. Could you setup minimal reproducible sample so I can reproduce.
RomanHotsiy
on 16 Mar 2018
great work, everything fixed except that subtle issue with scrolling
misos1
on 16 Mar 2018
@RomanGotsiy Thanks, Roman! I made the adjustments and everything looks good.
The discriminator-selector issue I described is much better, but still has a weird behavior. Everything is functional and accurately displayed, but the initial selection is the 5th item (or -2 going backwards) on my list. Perfectly acceptable in an alpha release, though.
trip-somers
on 16 Mar 2018
Using the following OpenAPI schema with redoc 2.0.0.15 alpha, the _externalDocs_ tag dos not show anything :
openapi: 3.0.0
info:
title: REST API Documentation
version: 1.0.0
paths:
/version:
get:
summary: Version Query
description: Retrieves a version string.
responses:
'200':
description: OK - Version retrieved.
content:
application/json:
schema:
type: object
properties:
version:
type: string
description: Version string. Includes product name, version number and build date.
externalDocs:
description: Implementation details.
url: "./details/implementation.md"
I understood that #103 added display of _externalDocs_ item. The above schema has been validated against the openapi 3.0 schema. Thanks !
svart-riddare
on 22 Mar 2018
After changing from 1.x to 2.0.0-alpha.17 i have noticed the following problems:
whenever i reference to an object, it only displays the name of the object, but not the corresponding attributes. I have noticed, that whenever something is of type object the child-attributes are missing. for example arrays of non-object types on the other hand show the child-attributes just fine.
Array Example
Object Example
The default response type for all samples is incorrectly set to / but should be application/json.
e.g. the following json still produces two available responses and selects the empty one first
"examples": {
"application/json": {
"message": "I am at your service!"
}
}
Dalabad
on 28 Mar 2018
similar to the comment by @Dalabad , update from 1.21.2 to 2.0.0-alpha.17 shows that there are some issues with displaying array of objects
swagger: '2.0'
info:
title: DObjs API
version: '1'
consumes:
- application/json
produces:
- application/json
paths:
'/r':
post:
operationId: post
parameters:
- name: data
in: body
required: true
schema:
$ref: '#/definitions/Payload'
responses:
'200':
description: Payload with discount
schema:
$ref: '#/definitions/Payload'
definitions:
Entity:
type: object
properties:
id:
type: string
format: uuid
readOnly: true
Item:
properties:
name:
type: string
ComplexItem:
allOf:
- $ref: '#/definitions/Entity'
- properties:
name:
type: string
Payload:
allOf:
- $ref: '#/definitions/Entity'
- properties:
items:
type: array
items:
$ref: '#/definitions/Item'
complex_items:
type: array
items:
$ref: '#/definitions/ComplexItem'
frodeaa
on 31 Mar 2018
Overriding a definition property with a different type breaks OpenAPIParser.
Stacktrace:
Error: Uncopatible types in allOf at "#/components/schemas/CreateAccountResponse/properties/result"
at e.mergeAllOf (OpenAPIParser.ts:207)
at e.mergeAllOf (OpenAPIParser.ts:221)
at new e (Schema.ts:68)
at Schema.ts:194
at Array.map (<anonymous>)
at e.initDiscriminator (Schema.ts:193)
at e.init (Schema.ts:115)
at new e (Schema.ts:69)
at new e (MediaType.ts:29)
at MediaContent.ts:31
Sample Spec:
{
"swagger" : "2.0",
"paths" : {
"/account" : {
"post" : {
"tags": [
"semux"
],
"summary" : "Create account",
"description" : "Creates a new account.",
"operationId" : "createAccount",
"produces" : [
"application/json"
],
"parameters" : [
{
"name" : "name",
"in" : "query",
"description" : "Assigned alias to the created account.",
"required" : false,
"type" : "string"
}
],
"responses" : {
"200" : {
"description" : "successful operation",
"schema" : {
"$ref" : "#/definitions/CreateAccountResponse"
}
}
}
}
}
},
"definitions" : {
"ApiHandlerResponse" : {
"type" : "object",
"discriminator" : "ApiHandlerResponse",
"required" : [
"success"
],
"properties" : {
"success" : {
"type" : "boolean"
},
"message" : {
"type" : "string"
},
"result" : {
"type" : "object"
}
}
},
"CreateAccountResponse" : {
"type" : "object",
"allOf" : [
{
"$ref" : "#/definitions/ApiHandlerResponse"
},
{
"properties" : {
"result" : {
"type" : "string"
}
}
}
]
}
}
}
cryptokat
on 11 Apr 2018
Indented markdown in descriptions breaks redoc-cli bundle:
---
swagger: '2.0'
info:
title: API
version: v1
description: |
This is some description markdown
This markdown is indented so it's a code block
paths:
"/foo":
get:
produces:
- text/plain
$ redoc-cli bundle swagger/v1/swagger.yml
Prerendering docs
Cannot read property 'tokenizePlaceholders' of undefined
cheald
on 18 Apr 2018
Hello! I need some help troubleshooting an issue. I'm working on a React/yarn/webpack/babel application and followed the instructions in the "Usage as a React component" section on this page:
https://github.com/Rebilly/ReDoc
I did a "yarn add redoc" and got this in my package.json:
"dependencies": {
"redoc": "^2.0.0-alpha.17"
I then did the "Usage as a React component" steps, restarted my application, and I get this in the JavaScript console:
[Error] TypeError: external_react_["createContext"] is not a function. (In 'external_react_"createContext"', 'external_react_["createContext"]' is undefined)
(anonymous function) (Anonymous Script 4 (line 5913))
__webpack_require__ (Anonymous Script 4 (line 36))
...
Line 5913 of the anonymous function is the last line of this code:
// EXTERNAL MODULE: external "dompurify"
var external_dompurify_ = __webpack_require__(34);
// CONCATENATED MODULE: ./src/components/OptionsProvider.ts
var OptionsProvider_OptionsContext = external_react_"createContext";
Has anyone seen this error before? Any ideas on why this is happening?
Thank you!
xian594
on 18 Apr 2018
I believe the issue I'm seeing is due to my app using React 15. Looks like I need to upgrade to React 16, then ReDoc 2.x will work.
xian594
on 21 Apr 2018
Closing this issue as too loooong and unmanageable.
Please, open separate issues!
Thanks, everyone for participating ❤️!
It's getting more stable!
RomanHotsiy
on 1 Jun 2018
[email protected] doesn't work with redoc-cli, cause mobx was moved to DevDependencies and it results in throwing an error "Cannot find module mobx"
llirikkk
on 26 Jul 2018
Related issues
JonKohler
·
3Comments
gavinkalika
·
3Comments
karussell
·
3Comments
vietnguyen010
·
3Comments
shreyas-agnihotri
·
3Comments
Most helpful comment
Hey everyone,
I release a new alpha with most the issues fixed since the previous alpha. I can't answer to everyone so please check the latest alpha and if your issue is not fixed, let me know.
https://twitter.com/RomanHotsiy/status/974381615135719426
@misos1 links are not yet implemented. Track here https://github.com/Rebilly/ReDoc/issues/437
@trip-somers multiple discriminators are not working yet. Regarding your last issue. You should reference schema not parameter:
$ref: '#/components/schemas/RequestHeaders/schema'(noticeschemain the end)@magnusros yes, this seems to be correct. Could you setup minimal reproducible sample so I can reproduce.