redocly / redoc Goto Github PK
View Code? Open in Web Editor NEW📘 OpenAPI/Swagger-generated API Reference Documentation
Home Page: https://redocly.github.io/redoc/
License: MIT License
📘 OpenAPI/Swagger-generated API Reference Documentation
Home Page: https://redocly.github.io/redoc/
License: MIT License
properties: {
"$ref": {
"type": "string"
},
...
}
In this schema $ref
is not the pointer but the field name
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.
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
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.
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
If some language was selected for an operation this language should be automatically selected for all other operations (where it is specified)
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.
It would be nice to have possibility to download swagger file.
Currently,examples are handled only on the schema top level.
Need to use examples from properties as well
Idea of sandbox, live, integration, test, and other environments.
Add something like "Powered by ReDoc" to end of page.
@RomanGotsiy @adamaltman What do you think?
readOnly
- don't show readOnly fields in request schemareadOnly
in responseto be continued...
Need move some of removed unit tests to e2e:
Also need to add unit tests for services
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
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)
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
It would be useful to have stable CDN links for each release not just for most recent one.
Implement API Console functionality.
Each method in ReDoc will have a button: “Try this method” which will open interactive console modal window.
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
Should display some symbol (maybe asterisk *) to represent any type
On hover should display explanation
id:
description: The customer identifier string
readOnly: true
allOf:
- $ref: "#/definitions/ResourceId"
throws error but it is correct definition
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.
http://rebilly.github.io:80/SwaggerTemplateRepo/swagger.yaml" is not a valid JSON Schema
On big schemas IE11/Edge works slower relative to other browsers.
The key bottleneck is generation a lot of ui elements for schema representations
For example on this schema: https://apis-guru.github.io/api-models/instagram.com/1.0.0/swagger.json
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:
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.
The issue was reported by @karussell here: APIs-guru/openapi-directory#83 (comment)
Currently all parameters dump together in one list.
It should be separate lists for different parameter type, like: header, body, query, path, etc.
min, max, items, etc.
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.
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.
Currently, you can't simply select a sample and copy it since you lose all indentation.
Plus you need manually uncollapse all levels.
x-code-samples
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
A declarative, efficient, and flexible JavaScript library for building user interfaces.
🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
An Open Source Machine Learning Framework for Everyone
The Web framework for perfectionists with deadlines.
A PHP framework for web artisans
Bring data to life with SVG, Canvas and HTML. 📊📈🎉
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
Some thing interesting about web. New door for the world.
A server is a program made to process requests and deliver data to clients.
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
Some thing interesting about visualization, use data art
Some thing interesting about game, make everyone happy.
We are working to build community through open source technology. NB: members must have two-factor auth.
Open source projects and samples from Microsoft.
Google ❤️ Open Source for everyone.
Alibaba Open Source for everyone
Data-Driven Documents codes.
China tencent open source team.