scalar
Multiple OpenAPI documents
Discussed in https://github.com/scalar/scalar/discussions/1379
Originally posted by rexvel April 4, 2024 What do you think about supporting multiple API specifications to display on a single page? The files could be merged into one to fit the current scalar component's API (React, in my case).
For instance, if I have APIs X, Y, and Z, I'd like to display them on a single page, where each API would have its own separate section (similar to the pet, store, and user sections in the Petstore example).
Here's how the navigation might look. Additionally, such changes would require support for nested navigation for endpoints, in my opinion.
We can use the new sidebar and have these specs as a "collection" that should just work
Once Scalar supports multiple OpenAPI documents, we could also refactor the Scalar.AspNetCore package a bit. Currently, the document name is part of the route and is required. Moving this information to the options could allow developers to add multiple documents during configuration. Additionally, we could explore ways to fetch the registered OpenAPI documents automagically, so the developer doesn't need to do anything.
Hi @xC0dex is this feature being worked on internally, or would you accept a PR for this? This is the main feature that is lacking from our point of view, so I'm keen to help bring this to fruition if it helps expedite this feature.
We’re working towards it, but it’ll be a longer endeavour. Once it’s done, it’ll be awesome for sure. :)
Just wanted to highlight that for our company, and likely many others, this is the key missing feature preventing us from fully switching from Swagger to Scalar in .NET. Hoping for its inclusion soon!
I was looking here to see if this could be done, currently we use https://github.com/andreytreyt/yarp-swagger. Reverse-Proxy aggregates backend apis and the dev/user can switch between them.
Also hope for this feature to integrate multi openapi documents more easily
This prevents me from switching too. My APIs are versioned (using the Content-Type header) and currently I'm generating one definition for each version and SwaggerUI lets me pick the version in the dropdown at the top.
im also waiting for this. kind of essential when using proxy gateway for your services
Just wanted to highlight that for our company, and likely many others, this is the key missing feature preventing us from fully switching from Swagger to Scalar in .NET. Hoping for its inclusion soon!
Same
I wanted to express my support for the feature request mentioned in issue #1851. I believe this feature would be highly beneficial for my use case as well. It addresses a gap that I have encountered in my workflows and would greatly enhance the usability of Scalar for my projects.
Thank you for considering this enhancement, and I hope it gains traction with the community.
Bumping for visibility this is a much-needed feature to be a true replacement for swagger! @geoffgscott @xC0dex any info about timelines for this feature?
Droped the similar request through discord channel aproximately a month ago, hoping to see Scalar will have this feature soon!
Now that's .net9 is out and Swagger is not in the standard, I tried Scalar and it was so good, but yes, I cannot use it with my Yarp proxy. Sad to be forced on SwaggerUI because multi-docs is missing ;)
Can we now create 2 urls for two different json ?
endpoints.MapScalarApiReference(opt =>
{
opt.OpenApiRoutePattern = "/swagger/api/swagger.json";
opt.Url = "scalar";
});
endpoints.MapScalarApiReference(opt =>
{
opt.OpenApiRoutePattern = "/swagger/api2/swagger.json";
opt.Url = "scalar2";
});
Can we now create 2 urls for two different json ?
endpoints.MapScalarApiReference(opt => { opt.OpenApiRoutePattern = "/swagger/api/swagger.json"; opt.Url = "scalar"; }); endpoints.MapScalarApiReference(opt => { opt.OpenApiRoutePattern = "/swagger/api2/swagger.json"; opt.Url = "scalar2"; });
Looking through the .net code i don't think you can add 2 instances like this. The .net code could however easily be changed to allow multiple instances. This issue is more about scalar as in the ui supporting multiple apis.
Hey @sorcerb,
It is possible to provide multiple MapScalarApiReference endpoints. We do this already in the playground project. However, this is not what this issue is about.
We also currently have multiple instances registered and one page with a top bar and an iframe below it to switch between them. Was easy to do and looks so seamless, that users don't even notice the "hack".
So it looks like this is now supported? Is there an example of how this would be specified with the endpoints.MapScalarApiReference
For all .NET devs: PR https://github.com/scalar/scalar/pull/5029 updates the integration and documentation 👀. Once merged, the next minor release of Scalar.AspNetCore will let you add as many docs as you want!
@nat45928 Here you go
<script type="module">
import { createScalarReferences } from 'https://esm.sh/@scalar/api-reference'
const el = document.getElementById('api-reference')
const reference = createScalarReferences(el, {
theme: 'purple', // alternate, default, purple, solarized, bluePlanet, saturn, kepler, mars, deepSpace, none
spec: {
sources: [
{
title: "Public Spec",
url: '/path/to/openapi-internal.yml'
},
{
title: "Private Spec",
url: '/path/to/openapi-internal-private.yml'
},
...
]
},
...
})
</script>
@cinchy-m Any change you could provide a more complete example?
Right now I have something like this but it's not rendering the multiple docs.
<!doctype html>
<html>
<head>
<title>Scalar API Reference</title>
<meta charset="utf-8" />
<meta
name="viewport"
content="width=device-width, initial-scale=1" />
<link rel="stylesheet" href="stylesheets/scalar.css">
</head>
<body>
<script
id="api-reference"
data-url="openapi/doc1.json">
</script>
<script>
// see https://github.com/scalar/scalar/blob/main/documentation/configuration.md
var configuration = {
theme: "default",
favicon: 'assets/favicon.png',
hideClientButton: true,
servers: [ ... ],
authentication: { ... },
};
document.getElementById("api-reference").dataset.configuration =
JSON.stringify(configuration);
</script>
<script src="https://cdn.jsdelivr.net/npm/@scalar/api-reference"></script>
<script type="module">
import { createScalarReferences } from 'https://esm.sh/@scalar/api-reference'
const el = document.getElementById('api-reference')
const reference = createScalarReferences(el, {
spec: {
sources: [
{
title: 'doc1',
slug: 'doc1',
url: 'openapi/doc1.json',
},
{
title: 'doc2',
slug: 'doc2',
url: 'openapi/doc1.json',
},
{
title: 'doc3',
slug: 'doc3',
url: 'openapi/doc1.json',
},
],
},
})
</script>
</body>
</html>
@nat45928 Yeh after I posted that comment I was working on mine and noticed this broke somewhere between 1.26.2 and latest, possibly in #5013, so I pinned the version in the CDN URL to 1.26.2 (https://esm.sh/@scalar/[email protected]) and what I pasted earlier now works.
Looks like there's a few PRs that update docs, e.g. #5159, so it might be worth following those to see if you can get latest to work but for me it's the addition of the spec.sources array that seems to break things, even following the new docs.