http://spacetelescope.github.io/understanding-json-schema/reference/object.html#properties

Currently all parameters dump together in one list.
It should be separate lists for different parameter type, like: header, body, query, path, etc.

On big schemas IE11/Edge works slower relative to other browsers.

The key bottleneck is generation a lot of ui elements for schema representations

Currently Bower package has to many unneeded files and dirs:

$ ls bower_components/redoc/ -1
bower.json
dist
docs
gulpfile.js
karma.conf.js
LICENSE
package.json
protractor.conf.js
README.md
system.config.js

There is a relatively insignificant bug in ReDoc- for every URI path, there is a whitespace char between the end of the root path (e.g. "v2.1") and "/{path}" - that is causing copy/paste errors in the documentation:

https://api.rebilly.com/v2.1 /organizations

Set appropriate headers to allow for gzip compression.
Discovered by Google's PageSpeed Insights: https://developers.google.com/speed/pagespeed/insights/?url=http%3A%2F%2Frebilly.github.io%2FReDoc%2F&tab=mobile

On the demo page, there seem to be code samples support for C# and PHP. Is there support for, or plans to implement, JavaScript request snippets?

No space between parameter name and description

properties: {
  "$ref": {
    "type": "string"
  },
  ...
}

In this schema $ref is not the pointer but the field name

Should display some symbol (maybe asterisk *) to represent any type
On hover should display explanation

• securityDefinitions
• add security definitions to the side menu
• security

• code
• tables
• lists
• blockquotes

http://rebilly.github.io:80/SwaggerTemplateRepo/swagger.yaml" is not a valid JSON Schema

• readOnly
• minLength
• maxLength
• pattern
• minItems
• maxItems
• multipleOf
• defaults
• file payload
• readOnly - don't show readOnly fields in request schema
• No need to mark readOnly in response

to be continued...

When response sample is not provided by API description (in Swagger format) it would be great to see automatically generated sample based on the model of response object instead of Sample unavailable message.

Something similar to what Swagger UI does, see "Example value" in Swagger UI demo.

Idea of sandbox, live, integration, test, and other environments.

From Swagger 2.0 spec:

Used to describe the payload of an HTTP request when either application/x-www-form-urlencoded, multipart/form-data or both are used as the content type of the request

It's good to show which mime types supported for 'form' parameters in this particular method.

For example use this url in demo:
https://apis-guru.github.io/api-models/bikewise.org/v2/swagger.yaml
And get link to first method:
http://rebilly.github.io/ReDoc/#operation/GET--version-incidents---format-

Demo could support specifying Swagger url through query parameter
So you can provide test links:
http://rebilly.github.io/ReDoc?url=http://petstore.swagger.io/v2/swagger.json
And correct links to method:
http://rebilly.github.io/ReDoc?url=http://petstore.swagger.io/v2/swagger.json#operation/GET--version-incidents---format-

See SwaggerUI for implementation:
https://github.com/swagger-api/swagger-ui/blob/master/dist/index.html#L35-L38

It would be great to implement an in-page search with results highlighting similar to something available here: http://docs.fidor.de (just enter the word "unique" within the search input field and click on one of the found references)

If you look at http://docs.fidor.de/javascripts/all.js there are a lot of open source JavaScript libraries that helps to implement search and highlight the results, like:

• http://lunrjs.com (full-text search)
• http://tartarus.org/~martin/PorterStemmer/js.txt (removes morphological and inflexional endings from words in English, see http://tartarus.org/~martin/PorterStemmer)
• http://johannburkard.de/blog/programming/javascript/highlight-javascript-text-higlighting-jquery-plugin.html (text highlighting)
• and others

Looks like it is possible to implement an in-page search with support from those libraries that would add a lot of credits to the wonderful ReDoc project! This may become a killing feature of the project ;)

Thank you in advance!

ReDoc doesn't use features of swagger-parser. So it makes sense to use underlying lib BigstickCarpe/json-schema-ref-parser as it is more lightweight.

Button which allow user to suggest changes in text.
@adamaltman Thank you for idea.

Advanced version could be Swagger spec opened in http://editor.swagger.io/ and allow to submit PR directly from it.

Add dropdown to let visitors test ReDoc on schemes other than Petstore.

• instagram by @darklynx
• trello ?
• other?

Currently,examples are handled only on the schema top level.
Need to use examples from properties as well

Add something like "Powered by ReDoc" to end of page.
@RomanGotsiy @adamaltman What do you think?

It would be useful to have stable CDN links for each release not just for most recent one.

Currently, you can't simply select a sample and copy it since you lose all indentation.
Plus you need manually uncollapse all levels.

Currently, they are ordered alphabetically (unintentionally: order of children definitions in spec).
Better would be to sort them in the same order as in enum
Rebilly/RebillyAPI#29 (comment)

id:
  description: The customer identifier string
  readOnly: true
  allOf:
    - $ref: "#/definitions/ResourceId"

throws error but it is correct definition

Implement API Console functionality.

Each method in ReDoc will have a button: “Try this method” which will open interactive console modal window.

There is the list of key features that should be implemented in the first version:

• Ability to send GET, POST, PUT, DELETE, UPDATE requests
• Ability to input/use/save authorization credentials
• Show UI for easy entering parameters for path, headers, query and body (payload) parameters
• UI should show selectbox for enums, checkboxes for boolean, text input for other simple types
• Request should be validated before send according to OpenAPI spec
• Support different environments (e.g. sandbox, dev, testing, etc) through OpenAPI vendor extension (each env will have unique base url and description) + ability to set default env specially for API-console
• For most parts response will be shown “as is”. JSON response will be only prettified (with possibility of collapsing). The other responses will be represented as strings.
• Show response headers that are documented in swagger. HTTP response headers that are not documented will be hidden under “Show undocumented response headers” button

I think it good to add help message (round icon with question mark) describing different types of parameters, especially for things like form or body parameters.

min, max, items, etc.

For example here: http://rebilly.github.io/ReDoc/#operation/updatePet
name, photoUrls, petType should be marked as required, see:
https://github.com/Rebilly/ReDoc/blob/master/demo/swagger.yml#L791-L794

@adamaltman Thank you for reporting this issue.

As suggested by @darklynx in #6

Possibility to configure displayed error level (warnings/errors), possibility to disable any warnings/errors.
Also show general errors (loading, parsing error)

• general errors (404 while loading file, parsing error)
• internal errors
• warnings

It would be nice to have possibility to download swagger file.

x-code-samples

Look at this before and after it's expanded. Notice the strange character in the contracted version:

For example on this schema: https://apis-guru.github.io/api-models/instagram.com/1.0.0/swagger.json

It would be useful to have script or tool to run in browser tests on user's Swagger spec.
It could be as simple as running a headless browser and check that there is no errors or warnings.
Would be the ideal test to integrate into CI just before deploying Swagger spec.
Important thing is to output banner which explains that this errors could be unrelated to Swagger spec but purely ReDoc issues and if so ask user to open issue in ReDoc repo.

Need move some of removed unit tests to e2e:

• click on menu item should scroll to element
• scroll down/up should update active item in menu
• expand schema
• discriminator buttons
• expand examples
• permanent links

Also need to add unit tests for services

The issue was reported by @karussell here: APIs-guru/openapi-directory#83 (comment)

If some language was selected for an operation this language should be automatically selected for all other operations (where it is specified)

As suggested by @adamaltman:

idea is to give users the ability to comment on endpoints (like for example, tweets, facebook comments, disqus, etc...)
I was thinking that some may not want a DB, and use a 3rd party for comments like facebook comments https://developers.facebook.com/products/social-plugins/comments