OpenAPI - support for relative documents with embedded schema

[System-Glitch]

Hello, the OpenAPI integration is a really useful feature. We would like to use it. However, due to the size of our spec, we split it in several files using relative document refs, like so:

paths:
  /profile:
    $ref: "./paths/profile.yml#/components/pathItems/profile"

This is described as valid in the OpenAPI spec, under the "Reference Object -> Relative Documents with Embedded Schema Example".

Is it supported by Gitbook? If yes, how do you make it work? I can only select one file per OpenAPI block. When they use a relative document ref, the block appears either empty or with ref errors.

If it's not supported, are there any plans?

[SamyPesse]

Hey @System-Glitch, we do support $ref to external documents when using a URL instead of uploading an OpenAPI file. We don't currently support it when uploading files; we might look into supporting it, but it has not been a common request/case so far.

At this stage, my suggestion will be to either:

• Host your OpenAPI files on a public server and reference the URL of the main one when inserting OpenAPI blocks in GitBook. GitBook will automatically fetch the other files and dereference on the fly when rendering the block
• Dereference the OpenAPI spec in a build step. It can be done with redocly bundle command.

For our API documentation, this is something we do as part of our deployment: https://api.gitbook.com/openapi.yaml

Where are you currently storing your OpenAPI files? On GitHub, next to the docs markdown files?

We are working on some improvements to our OpenAPI support, so let us know any feedback you have :)

[System-Glitch]

Thank you for your quick response! We will try using the URL method. We currently host a rapidoc website and we wanted to migrate to gitbook so our docs are centralized.

The spec files live in the same git repository as the project itself on gitlab and we wanted to synchronize them with gitbook using a CI pipeline, as explained here. This would also work for us even if we need to host the files ourselves.

If this can be helpful, here is one more detail for our use-case: we have multiple files and some can be in subdirectories. We have an "examples" directory with sub-directories for each feature. We store the example files there. It looks like this:

.
├── examples
│   ├── feature_1
│   │   └── create.json
│   ├── validationError.json
│   └── feature_2
│       ├── create_1.json
│       └── create_2.json
├── models.yml
├── openapi.yml
├── parameters.yml
├── paths
│   ├── feature_1.yml
│   └── feature_2.yml
├── responses.yml
└── types.yml

I'll continue experimenting using your suggestions and come back to you. Thank you.

[System-Glitch]

I managed to import the openapi files hosted on our rapidoc website directly into gitbook using the URL method. 👍🏻 I had to tweak the CORS settings a bit of course.

I think the current level of support is too light for our use-case.

• Some information from the spec file are not displayed (api version, api servers, top-level descriptions, authentication details, ...). This is not a big deal, we can still write those in regular blocks like the rest of the documentation.
• The UI doesn't show the examples for both requests and responses. The response displayed is only a representation of the response schema, which is not always as useful as manually written examples. This is very important to us for some complex requests. I know this has been reported already by other users.
• The window that opens on clicking "test it" is completely empty. I'm not exactly sure why, and I can't see any error in the browser console. Maybe it's because I'm only in preview mode in an unmerged draft?
• I was confused by some __$REFRESOLVED blocks that were generated alongside every path in our spec. I'm not sure what they're supposed to represent. I just removed them manually from the page afterwards.
  
• Finally, some paths randomly do not appear in the navigation in the top right of the page. They do appear while in the editor though, but not in preview mode.

For now we will continue working with rapidoc, but we are still interested in the possible future developments of gitbook in these regards. I hope this feedback has been valuable to you.