Scalar

Beautiful API references from Swagger/OpenAPI files

OpenAPIDocumentation
scalar/scalarscalar.com/swagger-editor@scalar/api-reference

README

Scalar API Reference


Generate interactive API documentations from Swagger files. Try our Demo

Features


- Uses Swagger/OpenAPI spec files
- Request examples for a ton of languages + frameworks
- Has an integrated API client
- Edit your Swagger files with a live preview
- Doesn’t look like it’s 2011

Scalar Townhall on Thu Mar, 28th in Discord

>

Join us to see upcoming features, discuss the roadmap and chat about APIs with us. 💬


Getting Started


From a CDN


  1. ```html
  2. <!doctype html>
  3. <html>
  4.   <head>
  5.     <title>API Reference</title>
  6.     <meta charset="utf-8" />
  7.     <meta
  8.       name="viewport"
  9.       content="width=device-width, initial-scale=1" />
  10.   </head>
  11.   <body>
  12.     !-- Add your own OpenAPI/Swagger spec file URL here: -->
  13.     !-- Note: this includes our proxy, you can remove the following line if you do not need it -->
  14.     !-- data-proxy-url="https://api.scalar.com/request-proxy" -->
  15.     <script
  16.       id="api-reference"
  17.       data-url="https://petstore3.swagger.io/api/v3/openapi.json"
  18.       data-proxy-url="https://api.scalar.com/request-proxy"</script>
  19.     !-- You can also set a full configuration object like this -->
  20.     !-- easier for nested objects -->
  21.     <script>
  22.       var configuration = {
  23.         theme: 'purple',
  24.       }
  26.       var apiReference = document.getElementById('api-reference')
  27.       apiReference.dataset.configuration = JSON.stringify(configuration)
  28.     </script>
  29.     <script src="https://cdn.jsdelivr.net/npm/@scalar/api-reference"></script>
  30.   </body>
  31. </html>
  32. ```

You can also use the following syntax to directly pass an OpenAPI spec:

  1. ```html
  2. <script
  3.   id="api-reference"
  4.   type="application/json">
  5.   { … }
  6. </script>
  7. ```

If you’d like to add a request proxy for the API client (to avoid CORS issues):

  1. ```html
  2. <script
  3.   id="api-reference"
  4.   type="application/json"
  5.   data-proxy-url="https://api.scalar.com/request-proxy">
  6.   { … }
  7. </script>
  8. ```

With Vue.js


The API Reference is built in Vue.js. If you’re working in Vue.js, too, you can directly use our Vue components. Just install them:

  1. ```bash
  2. npm install @scalar/api-reference
  3. ```

And import the ApiReference component to your app:

  1. ```vue
  2. <script setup lang="ts">
  3. import { ApiReference } from '@scalar/api-reference'
  4. </script>

  6. <template>
  7.   <ApiReference />
  8. </template>
  9. ```

You can pass props to customize the API reference.

With React


The API Reference package is written in Vue, that shouldn’t stop you from using
it in React though! We have created a client side (untested on SSR/SSG) wrapper
in react.

  1. ```ts
  2. import { ApiReferenceReact } from '@scalar/api-reference-react'
  3. import React from 'react'

  5. function App() {
  6.   return (
  7.     <ApiReferenceReact
  8.       configuration={{
  9.         spec: {
  10.           url: 'https://petstore.swagger.io/v2/swagger.json',
  11.         },
  12.       }}
  13.     />
  14.   )
  15. }

  17. export default App
  18. ```

With Nextjs


Our Next.js handler makes it easy to render a reference, just add it to an Api
route handler:

  1. ```ts
  2. // app/reference/route.ts
  3. import { ApiReference } from '@scalar/nextjs-api-reference'

  5. const config = {
  6.   spec: {
  7.     url: '/swagger.json',
  8.   },
  9. }

  11. export const GET = ApiReference(config)
  12. ```

Read more: @scalar/nextjs-api-reference