redocly/redoc

📘 OpenAPI/Swagger-generated API Reference Documentation

redoc's Issues

Whitespace not trimmed before concatenating root path with dir paths

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

Auto-generate JavaScript request sample?

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?

Add help messages for different types of parameters

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.

Information from enums is not displayed

Add info about cdn usage to README

Nested schemas: styling is broken on 3rd level

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

Extend tests

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

Fields doesn't mark as required inside JSON Schema

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.

Provide CDN links for released versions.

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

Redoc is not working on IE9/IE10

Use json-schema-ref-parser instead of swagger-parser

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.

Use operationId (if specified) field in links for methods

Display securityDefinitions/security

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

Feature: synchronize code samples

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

x-environments

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

Code samples in documentation

x-code-samples

Handle parameter types without type

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

Enable compression for OpenAPI spec download

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

Generate curl samples for requests

Group operation parameters by type

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

API Console feature

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

Add button to copy request/reply samples

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

Strange character in contracted form

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

handle additionalProperties

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

Markdown elements styling

• code
• tables
• lists
• blockquotes

json-schema constrains for headers are not rendered

min, max, items, etc.

Added link to project into API documentation

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

Demo with non-default swagger file provide incorrect persistent links

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

Feature: add possibility to comment on endpoints

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

Show supported mime types for form parameters

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.

Feature: Add "Suggest edits" button.

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.

Make response samples expandable

Fonts on demo page are broken on firefox 46.0.1 under ubuntu 14.04.1

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

Relatively slow loading on IE11/Edge

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

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

Prepare deployment documentation

Handle examples on property level

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

Enhance ReDoc demo page: add other demo schemes

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

• instagram by @darklynx
• trello ?
• other?

Show errors and warnings in the top of the page

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

Add in-page search with result highlighting (feature request)

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!

allOf works incorrect

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

throws error but it is correct definition

Render JsonSchema constraints

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

Numeric fields: minimum, maximum info are not represented on UI

Generate response sample based on model description

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.

Discriminator buttons are ordered unclearly

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)

Schema representation issue on Safari

No space between parameter name and description

invalid JSON schema

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

Feature: "Download swagger" button

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

Cleanup bower package

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

Don't resolve $ref on properties level

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

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

redoc-cli: test script to run on user-supplied openapi spec

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.