2.0.0-alpha.x issues

[RomanHotsiy]

Leave any issues you found during testing 2.0.0-alpha.x releases here (just not to make so much noise in #327)

[SebastianStehle]

Awesome job :)

My swagger definition does not work yet: https://cloud.squidex.io/api/swagger/v1/swagger.json

[RomanHotsiy]

@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:

[MikeRalphson]

@RomanGotsiy are you passing options.patch and options.warnOnly in the conversion? I'd recommend it! Full options documentation.

[SebastianStehle]

Ok, I fixed it and there are no more warnings in the swagger editor:

https://gist.githubusercontent.com/SebastianStehle/33f9dd6c02ace0b60dd434d5354b3bbf/raw/e8701476e499fc25726ee755780adf614597ce91/Squidex.json

Now I get another error.

[RomanHotsiy]

@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

[SebastianStehle]

But with the updated spec I get the other error. But I am pretty sure that you will solve it :)

[MikeRalphson]

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.

[SebastianStehle]

Oh, sorry. Thats awesome. Even some of my problems with the stable version are fixed :)

[RomanHotsiy]

I've just published v2.0.0-alpha.2 with those issues resolved.

[SebastianStehle]

Works perfectly for my original definition :)

[mikunn]

@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 👍

[RomanHotsiy]

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!

[suds-kumar]

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);
      }

[mikunn]

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.

[MikeRalphson]

@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]

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'

[MikeRalphson]

@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.

[RomanHotsiy]

@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.

[MikeRalphson]

@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.

[mikunn]

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 👍.

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]

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! 😃

[MikeRalphson]

@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

[MikeRalphson]

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.

[mikunn]

@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 :)

[sudsk]

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...

[j26nz]

@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?

[MikeRalphson]

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.

[RomanHotsiy]

@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: webpack-contrib/uglifyjs-webpack-plugin#63, webpack/webpack#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]

@suds123 it doesn't support externalValue yet. It will be ready for the next alpha!
Thanks for the report!

[trip-somers]

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:

1. 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?
2. 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]

I'm back with an actual 2.0.0-alpha.12 issue.

DESCRIPTION:

I have a discriminator selector box that exhibits the following behavior:

1. Loads with first mapping selected, shows wrong fields.
2. 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.)
3. 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?

[ghola]

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:

1. Not highlighing the currently active object
2. Is there a way to not have it display object and 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:

[misos1]

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.

[theholiday]

BUG:
Not sure if this was mentioned somewhere above, but a really long JSON doesn't fit in the response area.

[misos1]

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]

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]

Seems openapi 3.0.0 links https://swagger.io/docs/specification/links/ are not implemented, they are not shown nowhere.

[misos1]

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]

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]

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

[trip-somers]

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

[trip-somers]

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).

[magnusros]

Running redoc@2.0.0-alpha.12 but didn't manage to get scrollYOffset to work. Is this correct?
options={{
scrollYOffset: 72,
}}

[RomanHotsiy]

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 #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.

[misos1]

great work, everything fixed except that subtle issue with scrolling

[trip-somers]

@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.

[svart-riddare]

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 !

[Dalabad]

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!"
    }
}

[frodeaa]

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'

[cryptokat]

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"
                        }
                    }
                }
            ]
        }
    }
}

[cheald]

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
[ReDoc Compatibility mode]: Converting OpenAPI 2.0 to OpenAPI 3.0
Prerendering docs
Cannot read property 'tokenizePlaceholders' of undefined```

[xian594]

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"](new RedocNormalizedOptions_RedocNormalizedOptions({}))', '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"](new RedocNormalizedOptions_RedocNormalizedOptions({}));

Has anyone seen this error before? Any ideas on why this is happening?

Thank you!

[xian594]

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.

[RomanHotsiy]

Closing this issue as too loooong and unmanageable.

Please, open separate issues!
Thanks, everyone for participating ❤️!

It's getting more stable!

[llirikkk]

redoc@2.0.0-alpha.30 doesn't work with redoc-cli, cause mobx was moved to DevDependencies and it results in throwing an error "Cannot find module mobx"