redoc
redoc copied to clipboard
Redocly
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
Do you have a timeline for this feature? If you are done with it, SwaggerUI should be replaced by Redoc as the official solution ;)
@SebastianStehle can't promise anything. It is on our list but before we have a few other things to implement. I will update the roadmap shortly.
Hopefully, we will get this ready in 3-4 months
API Console is one of the priorities now. But so far we haven't started working on that :( This seems to be the next big task on our roadmap. I will post here once we start work on this.
About the support for "different environments" in the description of this issue, I don't think this should be a priority: the host and the basePath are specified in the Swagger spec and allowing to switch environments would imply to override the information from the spec. But there would be a much simpler to way to have this feature: have multiple instances of ReDoc with its own spec with the specialized spec with the specific host/basePath settings. That's how I'm handling multiple environments with swagger-ui right now.
Note that sandbox/dev/testing environments are usually not information you want to expose (and accidentally leak), so using a vendor extension of the spec does not seem to be the right place.
Please stop adding "+1" comments. Use instead the reaction feature of GitHub.
You can even delete your own useless comments!
Hey @RomanGotsiy Thanks for such an awesome API documentation tool :) Are you currently working on implementing API console ? Do you have any timeline for this feature?
@j26nz no, I'm on 2-week vacation now and don't have any timeline for now. I have this partially implemented for very simple use-cases but swagger has so many ways to describe the same thing that there's still a lot of work to finish this.
I will try to keep all you guys updated on the progress
@RomanGotsiy - did you all look into the support that Postman has for generating collections from swagger? (you have to scroll down a bit)
I'm not saying that there's no reason for ReDoc to have a console, but if there's another workable option, I wonder if there are other features that would be more valuable. Especially when I think about not only the complexity of supporting the multiple ways of expressing the same thing that OpenAPI supports, but also the tough time properly supporting built-in security features and allowing for user extensions.
I know the community is really looking forward to a built-in console, but having come to ReDoc from the disappointments of SwaggerUI, I'd hate to see this great tool get bogged down in the implementation and support of a "nice to have" feature when there are workable alternatives.
I hope over the next few days to look into Postman's support and will share my experience here too.
Update on trying out Postman-generated collections, first impressions:
- imported a couple specs that make use of "advanced" OpenAPI features without issue, including:
- use of
discriminator(polymorphic types) - use of
additionalProperties
- use of
- interpretation of markdown in descriptions (including tables and fenced code) ...
- (this is a little bit handy, but I'd still have the ReDoc rendering for real documentation)
- ability to add a pre-request script for calculating any security headers
Generated Postman collections look good for our use cases, at least. We'll proceed beyond the quick POT I've done and see what more we learn.
@RomanGotsiy (and others) I would be really interested in hearing about your exploration of generated Postman collections and understanding what advantages a custom built-in API console has over them.
I have this partially implemented for very simple use-cases but swagger has so many ways to describe the same thing that there's still a lot of work to finish this.
@RomanGotsiy you can release a very simple version. After releasing, people interested in more features will create new issues.
hey @RomanGotsiy like @raderio said Is it possible for you to release a simple version of API console or you can put it on a separate branch and people interested in more features can start contributing to it. Thanks.
hi is there any update on this feature. May be we can have a PR for this??
@indolent-developer @j26nz @raderio sorry for the long delay. The last couple of months were pretty busy for me.
For those who haven't seen it yet, I'm migrating ReDoc to React. Here is the corresponding issue to track: https://github.com/Rebilly/ReDoc/issues/327
Console feature is definitely the next in the queue but there is no point to work on it before I finalize React version.
Thanks for being patient and for pinging me! It really motivates me to work on this!
This is a great feature for us. It would be useful to have in ReDoc (vs. Postman) for us because we want to provide an integrated online experience.
@RomanGotsiy Do you have a better idea when this can be available now? It looks like #327 is nearing completion but it is still open and the latest release is v2.0.0-alpha.5.
Per @j26nz and @indolent-developer, if it will speed things up, is it possible to allow others to start working on this to send a PR?
Hey @RomanGotsiy ! is this feature still on roadmap and is something will see soon?
@grokify @j26nz this feature is still on the roadmap! T
I just have to finalize #327. There is a bit of dirty work left that I want to finish before letting other to start working on this. I will try my best to finish this asap (ETA is 1 week)
Also, I have already implemented a dead-simple try-with console based on angular version. I can't share it but I think I know where should we start from. I will share updated requirements for this feature soon.
Great @RomanGotsiy! We'll try out v2.0.0-alpha.10 and let you know our feedback.
Thanks @RomanGotsiy. Did you get a chance to update requirement for this feature? Thanks.
A word of caution when implementing this for API console purpose is to handle redirects properly. Browsers follow redirect transparently. There is no way to prevent it in XHR, but the Fetch API allows redirect: manual as an option when creating a request. This will make sure that the browser does not automatically follow if the returned response is 3xx which might be the expected response as per the documentation of a specific API endpoint. If the browser follows redirects then the console will never be able to show what was returned from the server. Imagine documenting a URL shortner service API where a 301 response with an appropriate Location header woyld be more interesting than letting the console dereference and load the eventual URL.
