redoc: Can't fetch local file

workaround to have a web server will not work if one needs to send a static html/js documentation to a person that only has a browser …

@vishesh1king just serve your spec and html page via any http-server (e.g. python -m SimpleHTTPServer) so url to it will be: http://127.0.0.1:<someport>/swagger.json not file:///<path>/swagger.json

@hmasila the reporter clearly stated that the “http://” works for him (and for others too).

This ticket is about “file://” protocol support. So that we can send a “ZIP” to a person that doesn’t have knowledge to run a web server on their computer, or simply has no time to do it.

@nthx I came across this thread when I was working with a local json file. It took me a while to pass it to the redoc tag as http. That is why I wrote my comment. To help any other person who might be in the same situation.

Here is what worked for me.

1. Create OpenAPI/Swagger in swagger.io
2. Download OpenAPI as JSON
3. Create a Node.js app with Express. - or any server you are comfortable with
4. Set an endpoint in the server.js that points to a middleware that mocks the json
5. Add the newly created endpoint to the <redoc>"http://localhost:5555/api/v1/test</redoc>
6. Fire up your server
7. Go to the route where you added redoc
8. Sit back, relax and enjoy!!

The reason is that the lib I use (json-schema-ref-parser) doesn’t support file:/// protocol.

I will fix this but this is not on the next-to-do queue coz this can be workarounded by simply running webserver

Got it thanks … But do you have any format on the json sytax ?? I am uable to load my custom json file … Its says " Oops… ReDoc failed to render this spec this._schema.info is undefined "

This is my main.json file: { “links”: { “self”: “http://example.com/articles”, “next”: “http://example.com/articles?page[offset]=2”, “last”: “http://example.com/articles?page[offset]=10” }, “data”: [{ “type”: “articles”, “id”: “1”, “attributes”: { “title”: “JSON API paints my bikeshed!” }, “relationships”: { “author”: { “links”: { “self”: “http://example.com/articles/1/relationships/author”, “related”: “http://example.com/articles/1/author” }, “data”: { “type”: “people”, “id”: “9” } }, “comments”: { “links”: { “self”: “http://example.com/articles/1/relationships/comments”, “related”: “http://example.com/articles/1/comments” }, “data”: [ { “type”: “comments”, “id”: “5” }, { “type”: “comments”, “id”: “12” } ] } }, “links”: { “self”: “http://example.com/articles/1” } }], “included”: [{ “type”: “people”, “id”: “9”, “attributes”: { “first-name”: “Dan”, “last-name”: “Gebhardt”, “twitter”: “dgeb” }, “links”: { “self”: “http://example.com/people/9” } }, { “type”: “comments”, “id”: “5”, “attributes”: { “body”: “First!” }, “relationships”: { “author”: { “data”: { “type”: “people”, “id”: “2” } } }, “links”: { “self”: “http://example.com/comments/5” } }, { “type”: “comments”, “id”: “12”, “attributes”: { “body”: “I like XML better” }, “relationships”: { “author”: { “data”: { “type”: “people”, “id”: “9” } } }, “links”: { “self”: “http://example.com/comments/12” } }] }

ReDoc demo spec in yaml format

If you are not familiar with OpenAPI you can start from template spec (direct link). You should also check series of tutorials by API Handyman: http://apihandyman.io/writing-openapi-swagger-specification-tutorial-part-1-introduction/

passing the local spec_file path to the redoc docker container is also a really convenient route (if you have docker installed)

docker run -it --rm -p 81:80 \
  -v $(pwd)/<SPEC_FILE>:/usr/share/nginx/html/<SPEC_FILE> \
  -e SPEC_URL=<SPEC_FILE> redocly/redoc

# visit localhost:81 in your browser

source https://hub.docker.com/r/redocly/redoc

^ for future viewers

redoc-cli has an ability to bundle spec into zero-dependency HTML file. Docs here: https://github.com/Rebilly/ReDoc/tree/master/cli

This would be another argument for rolling redocup into v2.0 as a cli feature. Then the FAQ can read:

Local files will not work, they need a file server to run due to [bla]. If you are working locally and want to see what your redoc will look like, simply use the cli tool: yarn run redoc serve.

Or something. 😃

I have investigated this issue and it seems loading local swagger spec is impossible without running web-server due to same-origin policy and security reasons.

I found other projects have the same issue not resolved, e.g.: https://threejs.org/docs/#manual/introduction/How-to-run-thing-locally.

workaround to have a web server will not work if one needs to send a static html/js documentation to a person that only has a browser …

I absolutely understand the use case though. There are two possible solutions to this use case:

• upload both html and spec to any static hosting so a person with a browser can access it
• inject spec directly into html so ReDoc doesn’t have to do any network requests (the spec should be bundled beforehand). This variant should be pretty easy after React rewrite is finalized: https://github.com/Rebilly/ReDoc/pull/357. I think it may be a good idea for an open-source tool. If anyone is willing to write it, let me know and will try to get you started.

If anyone though does know how to load local swagger spec, let me know!

I’m not closing this issue until F.A.Q. is created and this is included there.