This issue collects issues we need to tackle before launch:

Remaining Requirements

• #102
• #17
• #103
• #104

Expected Behavior

Currently there's no way to tell if a request/body is being mapped from an OpenAPI/Swagger model. We might want to have some indicator to if/what is being mapped. Maybe a chip/pill that links to the model?

OpenAPI models are listed, but there is no visible mapping between request's payload and response to them (request shows copy of the model, response shows only example/generated-example )

Actual Behavior

No mapping to openapi models from request/responses

Reproduction steps

load a swagger spec :) and you can see the lack of mapping✨

Version

latest

What browsers are you seeing the problem on?

No response

_DOC-1242

Expected Behavior

application/x-www-form-urlencoded can be used in the request body

Actual Behavior

Currently we only support application/json inside of https://github.com/scalar/scalar/blob/main/packages/api-reference/src/components/Content/ReferenceEndpoint/RequestBody.vue

Reproduction steps

Add a swagger file with a requestBody of not just application/json

Version

0.8.1

What browsers are you seeing the problem on?

No response

_DOC-1237

Expected Behavior

I can navigate to an endpoint from the sidebar or endpoint preview list when a tag is closed

Actual Behavior

No navigation happens

Reproduction steps

load petstore example
navigate to a closed tag
click an endpoint from the list of endpoints of a tag
wont navigate

Version

0.7.9

What browsers are you seeing the problem on?

Chrome

_DOC-1223

For instance, all parameters & bodies can have examples and we should have the ability to showcase the examples and also easily import them to use for a request

_DOC-1210

Currently, we’re providing headers, cookies, query params to the API Client. We should prefill the Authentication UI instead.

Expected Behavior

When clicking any endpoint link on the search modal, user should navigate to the desired link

Actual Behavior

Nothing happens

Reproduction steps

1. Go to https://docs.scalar.com/swagger-editor
2. Click on the Petstore example
3. Click on the Search text input, so the modal appears, click on any endpoint
4. Nothing happens

Version

latest

What browsers are you seeing the problem on?

Chrome

If an endpoint has a body schema, we should place that in the body in the rest API Client

_DOC-1209

For some reason the keyboard shortcuts are broken, or brake in some scenarios (cmd+a, cmd+f, cmd+z …).

Would be nice to have an Express middleware which is easy to add to an existing Express setup.

The CDN build is huge. Most of it is probably Node polyfills.

✓ 1609 modules transformed.
dist/browser/standalone.js  5,250.08 kB │ gzip: 1,181.41 kB

Let’s try to make it smaller.

Debugging

npx vite-bundle-visualizer -c vite.cdn.config.ts

At the first glance those make it big:

• @scalar/swagger-editor (make a build without the swagger editor?)
• CodeMirror
• icons (huge potential to reduce the build size)

The discord invite link in the README and on the website is expired.

We should set up a Vite SSG demo to make sure the component doesn’t break SSG.

Showing all models (~200) for large specs freezes the reference.

We should probably lazy render the models when they become visible.

We should add virtual scroll.

Expected Behavior

Loaded scalar from a CDN and not using a scalar request proxy. Issue a request. See the response.

Actual Behavior

The network inspector shows the response coming back successfully but the UI doesn't show it.

Reproduction steps

1. Find an operation
2. Issue a test request for it (maybe changing headers/etc to make it succeed)
3. See that only response duration is shown

Version

0.7.9

What browsers are you seeing the problem on?

Chrome

Expected Behavior

In the openapi spec (3.0.0), the path has security object it does not show up in the UI.

Actual Behavior

Path level security headers should be shown like is redocly or swagger editor

Reproduction steps

1. Go to https://www.frogment.com/edit/raj-debug/cashfree-oct18.json#paths/_orders.yaml
2. Click on Preview
3. Open a new tab an go to https://www.frogment.com/edit/raj-debug/cashfree-oct18.json#components/securitySchemes/XClientID.yaml

Version

CDN

What browsers are you seeing the problem on?

Firefox

We added the description headings to the sidebar, but they should also appear in the search.

Currently, the IntersectionObserver sets the URL. The URL is then set to the section that’s becoming visible, not to the active item (which is the first item in the sidebar, where the section visible).

Suggestion:

Get Help
If you can't get something to work the way you expect, open a question in our discussion forums.

Feature Request
Suggest any ideas you have using our discussion forums.

Bug Report
If you've already asked for help with a problem and confirmed something is broken, create a bug report.

Hi,

I tried to use the ApiReference in a new Vue project, but I'm getting. ReferenceError: process is not defined.

Reproduction steps:

• Create a new Vue project: npm create vue@latest.
• Install dependencies: npm install.
• Add @scalar/api-reference: npm install @scalar/api-reference
• Replace the contents of App.vue with:

<script setup>
import { ApiReference } from '@scalar/api-reference'
</script>

<template>
  <ApiReference spec-url="https://petstore.swagger.io/v2/swagger.json" />
</template>

• Start the project: npm run dev.
• Open the page & check the console.

Initially, I tried to do it in my existing project and got this error, so I thought maybe I'll try with a brand new project but it was still not working. I followed the exact steps above.

I can provide a reproduction repo if needed.

I'm on Node v18.17.1.

When I directly open a link to a collapsed section, the section should expand automatically.

Automatically call fastify.swagger() if @fastify/swagger is used. 🪄

The response headers are hidden. We need to find a way to fix the height problem for long lists of headers before showing it again.

The spec allows parameters to be defined on each operation or at the path level. When using them at the path level, like below. Scalar attempts to parse/render the parameters as a method/operation, instead of applying the parameters to every operation under that path.

openapi: '3.0.2'
info:
  title: Broken Params
  version: '1.0'
paths:
  /items/{id}:
    parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
    get:
      summary: Get Item
    put:
      summary: Update Item
    delete:
      summary: Delete Item

_{From SyncLinear.com | DOC-854}

When the API client modal is open, cmd+k doesn’t work.

We need to rethink the DOM API for the standalone version. Currently it looks like that:

<div spec="{…}">

But passing JSON as an HTML attribute isn’t as easy as it seems (#104). And it would be nice to add support for all ApiReference props.

WIP: #236

xmldom 0.6.0 is EOL and unmaintained, see README.md

It is replaced by @xmldom/xmldom

We’re using the current url (window.location) as a fallback for the server URL. There’s only one use case, where that’s helpful: When rendering the reference through the fastify plugin.

We should only use that as the fallback for the fastify plugin and need to make it a config option.

When scrolling through the description the sidebar item isn’t updated.

I think we need to extend the MarkdownRenderer to loop through the Markdown AST and wrap the sections in an IntersectionObserver component.

I created a new Vite app and added the ApiClient component from @scalar/api-client.

The build fails with the following message:

index-73bc151c.js:1 Uncaught TypeError: Cannot read properties of null (reading 'refs')

When changing the example request library, the example request code snippet becomes shorter/longer and the scroll position needs to be updated.

Let’s add anchor icons to all headings (Markdown, operations, models).

They should copy the link to the section on click.

Current approach was to use Netlify to build on push to main.

But what we really want is a standalone build on release.

I’m now trying to add the standalone build to the existing @scalar/api-reference package and use a public CDN. But that doesn’t work yet.

https://swagger.io/docs/specification/data-models/oneof-anyof-allof-not/

_DOC-1216

Example schema:

{
  "schema": {
    "type": "array",
    "items": {
      "type": "object",
      "properties": {
        "apr": {
          "type": "number",
          "minimum": 0
        },
        "date": {
          "type": "string"
        },
        "vault_address": {
          "type": "string"
        }
      },
      "required": [
        "apr",
        "date",
        "vault_address"
      ]
    }
  }
}

Expected Behavior

OpenAPI version: 3.0.0
This is a property name and it has a description.

NewPet:
  type: "object"
  required:
    - "name"
  properties:
    name:
      type: "string"
      description: "some desc"
    tag:
      type: "string"

UI does not load description

Full html

<!DOCTYPE html>
<html>
  <head>
    <title>Swagger Petstore - API Reference</title>
    <meta charset="utf-8" />
    <meta
      name="viewport"
      content="width=device-width, initial-scale=1" />
    
  </head>
  <body>
    <!-- Add your own OpenAPI/Swagger spec file URL here: -->
    <script
      id="api-reference"
      data-url="/json/raj12/pet_store.json"></script>
    <script src="https://www.unpkg.com/@scalar/api-reference"></script>
  </body>
</html>```



### Actual Behavior

Description to come in the UI

 


### Version

CDN

### What browsers are you seeing the problem on?

Chrome, Firefox

The models should appear in the search

null

_DOC-853

Too much duplicate code (in our main app and here), maybe we can move everything to packages or Idk. :)

• FlowModal

I’d expect the sidebar and the Swagger editor to be sticky, but they scroll out of view.

When an error in the Swagger editor appears, it won’t go away, even if the syntax error or whatever is fixed.

The SectionHeader uses h1 everywhere. We should only use h1 for the spec title, and h2 + h3 for the rest.

When generating an example response (or request body) from the schema, the min value is ignored.

Without an URL the send request button is disabled. For smaller screen it’s still enabled, or looks enabled.

We need some kind of CSS reset (no matter which, as long as we know what we’re building on). I just added a modern-normalize import recently, but instead of including it, it’s just kept as the import statement.

We need to make sure the import statement is resolved and the CSS is included, otherwise all projects need the reset as a dependency.