Redocly / Redocly/redoc

Reports unsupported specification when supplying it directly

Open
#2,485 1 comment 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Type: Bug
Dominant language
TypeScript
Stars
25.9k
Forks
2.4k
Avg merge
13h 10m
Merged PRs (30d)
4

Description

The OpenAPI 3.0.3 API definition I am trying to integrate into a project is served from API server as yaml. That yml file is valid, e.g. it opens and renders without issues when I try it online via https://redocly.github.io/redoc/. I am using internal http tools to fetch it's raw content due to JWT authentication. So, I am trying to render the docs via React component, like this:

import { observer } from 'mobx-react'
import { useViewModelFactory } from 'mobx-react-viewmodel'

import { ApiDocPageViewModel } from './api_doc.page.vm.ts'
import { RedocStandalone } from 'redoc';

export const ApiDocPage = observer(function ApiDocPage() {
  const { spec } = useViewModelFactory(() => new ApiDocPageViewModel())

  return (
    <RedocStandalone spec={spec} />
  )
})

The important part is the <RedocStandalone spec={spec} /> section. I checked the spec value and indeed it is a string that contains the API specification, e.g. starts like this:

openapi: 3.0.3
info:
  title: API
  version: '1.0'
servers:
  - url: '{server}/api/v1'
....

However, this results in:

Error: Unsupported specification
    at detectSpec (http://localhost:4010/node_modules/.vite/deps/redoc.js?v=7192a3a7:21531:13)
    at http://localhost:4010/node_modules/.vite/deps/redoc.js?v=7192a3a7:36716:56
    at Generator.next (<anonymous>)
    at http://localhost:4010/node_modules/.vite/deps/redoc.js?v=7192a3a7:36632:71
    at new Promise (<anonymous>)
    at __awaiter (http://localhost:4010/node_modules/.vite/deps/redoc.js?v=7192a3a7:36614:14)
    at bundleDocument (http://localhost:4010/node_modules/.vite/deps/redoc.js?v=7192a3a7:36714:14)
    at http://localhost:4010/node_modules/.vite/deps/redoc.js?v=7192a3a7:36701:16
    at Generator.next (<anonymous>)
    at http://localhost:4010/node_modules/.vite/deps/redoc.js?v=7192a3a7:36632:71
image

I kind of traced this error to https://github.com/Redocly/redocly-cli/blob/main/packages/core/src/oas-types.ts#L103, but not sure if it applies here. Seems it indeed can not recognize the API doc/spec flavor. Which is odd given it works correctly on https://redocly.github.io/redoc. I am using "redoc": "^2.1.3" dependency.

Any idea on what may be wrong in my setup?

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

The report names the RedocStandalone component and the detectSpec and bundleDocument stack frames; start there and compare how the hosted Redoc demo supplies the same YAML. Done means reproducing the failure with redoc 2.1.3 and documenting or correcting handling of the directly supplied specification.

Written by the indexing model from the issue text.

Assessment

Tech stack
react, typescript
Domain
api, documentation
Issue type
Bug
Difficulty
3/5
Estimated time
1-2 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
28/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.