Code Samples
Code Samples allow you to showcase API request examples in multiple programming languages. This feature helps API consumers understand how to integrate with your API using their preferred language.
You can customize:
- Available languages for selection (
availableLanguages) - The default language (
defaultLang) - How code is generated for each language (
generator)
Default Languages
Out of the box, vitepress-openapi includes the following languages:
| Language | lang | target / client |
|---|---|---|
| cURL | curl | shell / curl |
| JavaScript | javascript | js / fetch |
| PHP | php | php / curl |
| Python | python | python / requests |
You can filter, extend, or fully replace this list using availableLanguages.
Configuring Languages
Each language is defined as a LanguageConfig object:
| Property | Required | Description | Examples |
|---|---|---|---|
lang | Yes | Arbitrary identifier, used only for referencing | 'curl', 'my-lang' |
label | Yes | Name shown in the language selector | 'cURL', 'Python' |
target | No | Code generation target for @scalar/snippetz | 'shell', 'js', 'python' |
client | No | HTTP client library used in generated code | 'curl', 'fetch', 'axios' |
highlighter | No | Shiki language for syntax highlighting | 'bash', 'javascript', 'plain' |
icon | No | Icon identifier for vitepress-plugin-group-icons | 'curl', '.js', '.py' |
TIP
target and client must match a supported @scalar/snippetz plugin. For icon configuration, see custom icons.
Setting the Default Language
useTheme({
codeSamples: {
defaultLang: 'python',
},
})Filtering Default Languages
useTheme({
codeSamples: {
availableLanguages: useTheme().getCodeSamplesAvailableLanguages(['curl', 'python']),
},
})Adding Languages
Spread the defaults and add your own:
useTheme({
codeSamples: {
availableLanguages: [
...useTheme().getCodeSamplesAvailableLanguages(),
{ lang: 'csharp', label: 'C#', highlighter: 'csharp', icon: '.cs', target: 'csharp', client: 'httpclient' },
],
},
})Multiple Variants of the Same Language
You can add multiple entries for the same language with different clients. Use distinct label values to differentiate them in the UI:
useTheme({
codeSamples: {
availableLanguages: [
...useTheme().getCodeSamplesAvailableLanguages(['curl', 'python']),
{ lang: 'typescript', label: 'TS Fetch', highlighter: 'typescript', icon: '.ts', target: 'js', client: 'fetch' },
{ lang: 'typescript', label: 'TS Axios', highlighter: 'typescript', icon: '.ts', target: 'js', client: 'axios' },
],
},
})Custom Generator
For languages not supported by @scalar/snippetz, omit target and client and provide a custom generator. The generator receives (langConfig: LanguageConfig, request: OARequest) and should return a Promise<string>. Use generateCodeSample from vitepress-openapi/client as a fallback for built-in languages.
The example below adds Bru Markup Language with a custom generator that converts the request to Bru code.
Example
---
aside: false
outline: false
title: vitepress-openapi
---
<script setup lang="ts">
import { onBeforeMount, onBeforeUnmount } from 'vue'
import { useTheme, generateCodeSample } from 'vitepress-openapi/client'
onBeforeMount(() => {
useTheme({
codeSamples: {
availableLanguages: [
{
lang: 'bruno',
label: 'Bruno',
highlighter: 'plaintext',
},
...useTheme().getCodeSamplesAvailableLanguages(),
],
defaultLang: 'bruno',
generator: async (langConfig, request) => {
if (langConfig.lang === 'bruno') {
return generateBruRequest(request)
}
return generateCodeSample(langConfig, request)
},
},
})
})
onBeforeUnmount(() => {
useTheme().reset()
})
function generateBruRequest(request) {
const { url, method, headers, body, query } = request;
const methodLower = method.toLowerCase();
const queryString = query && Object.keys(query).length
? `${url}?${new URLSearchParams(query).toString()}`
: url;
const headersSection = headers && Object.keys(headers).length
? `headers {\n${Object.entries(headers)
.map(([key, value]) => ` ${key}: ${value}`)
.join('\n')}\n}`
: '';
const bodySection = body
? `body {\n ${JSON.stringify(body, null, 2).replace(/\n/g, '\n ')}\n}`
: '';
const bruRequest = `${methodLower} {
url: ${queryString}
}
${headersSection}
${bodySection}
`;
return bruRequest
.trim()
.replace(/\n{2,}/g, '\n\n') // Remove extra newlines
}
</script>
<OASpec />Preview
The Argentine Rock Legends is an example OpenAPI specification to test OpenAPI tools and libraries. Get all the data for all artists.
Inspired by Scalar Galaxy
Resources
- https://github.com/enzonotario/vitepress-openapi
- https://github.com/OAI/OpenAPI-Specification
Markdown Support
All descriptions can contain tons of text Markdown. If GitHub supports the syntax, chances are we’re supporting it, too. You can even create internal links to reference endpoints.
Examples
Blockquotes
I love Argentine Rock. <3
Tables
| Feature | Availability |
|---|---|
| Markdown Support | ✓ |
Accordion
<details>
<summary>Using Details Tags</summary>
<p>HTML Example</p>
</details>
Images
Yes, there’s support for images, too!
Contact
Servers
Artists
Everything about Argentine Rock artists and their contributions to music history.
Note: You will need to authenticate yourself to access some of these endpoints using the POSTAuthenticate a user endpoint.
Get all artists
Get a list of all legendary Argentine Rock artists and explore their contributions to the music scene. You can get one using the GETGet an artist endpoint.
Parameters
Query Parameters
The number of items to return
102050"int64"10The number of items to skip before starting to collect the result set
123456"int64"0Responses
Success Response
The request was successful and returns a list of artists.
Response Format
The response includes:
- A
dataarray containing artist objects - Pagination information
Note: You can use the pagination parameters to navigate through large result sets.
Add a new artist
Add a new legendary Argentine Rock artist. Make sure they truly deserve the title! You can view it later using the GETGet an artist endpoint.
Authorizations
Request Body
Responses
Artist Created Successfully
The artist has been successfully added to our database.
Response Details
The response includes the complete artist object with:
- A newly assigned unique
id - All the information you provided in the request
Get an artist
Learn more about a specific Argentine Rock artist and their legacy. You can update it using the PUTUpdate an artist endpoint.
Parameters
Path Parameters
1"int64"Responses
Artist Found
The requested artist was found and returned successfully.
Response Format
The response includes the complete artist object with all available details:
id: Unique identifier for the artistname: Full name of the artistdescription: Biographical informationimage: URL to the artist's photoband: Primary band association
Update an artist
Update the information of a legendary Argentine Rock artist. Make sure to provide accurate data. You can get the current data using the GETGet an artist endpoint.
Authorizations
Parameters
Path Parameters
1"int64"Request Body
Responses
Artist Updated Successfully
The artist information has been successfully updated in our database.
Response Details
The response includes the complete updated artist object with all the changes you made.
Note: All fields are returned in the response, even if you only updated some of them.
Delete an artist
This endpoint was used to delete artists. Unfortunately, that caused a lot of controversy. So, this endpoint is now deprecated and should not be used anymore. You can use the PUTUpdate an artist endpoint instead.
Authorizations
Parameters
Path Parameters
1"int64"Responses
Bad Request - Deprecated Endpoint
Get all albums
Get a list of all albums from a legendary Argentine Rock artist. You can add a new album using the POSTAdd a new album endpoint.
Parameters
Path Parameters
1"int64"Query Parameters
The number of items to return
102050"int64"10The number of items to skip before starting to collect the result set
123456"int64"0Responses
Albums Found
The request was successful and returns a list of albums for the specified artist.
Response Format
The response includes:
- A
dataarray containing album objects - Pagination information for navigating through large collections
Note: If the artist has no albums, the data array will be empty but the request will still return a 200 status code.
Add a new album
Add a new album to a legendary Argentine Rock artist. Make sure it's a masterpiece! You can view all albums using the GETGet all albums endpoint.
Authorizations
Parameters
Path Parameters
1"int64"Request Body
Responses
Album Created Successfully
The album has been successfully added to the artist's discography.
Response Details
The response includes the complete album object with:
- A newly assigned unique
id - All the information you provided in the request
- The association with the artist
Authentication
Some endpoints are public, but some require authentication. We provide all the required endpoints to create an account and authorize yourself.
Create a user
Create a user account to access exclusive content about Argentine Rock legends. After signing up, you can access endpoints like GETGet all artists to explore the data.
Request Body
Responses
User Created Successfully
Your account has been created and you can now access the Argentine Rock Legends API.
Response Details
The response includes your user information (excluding the password) and your API key for authentication.
Important: Save your API key securely as it will be needed for authenticated requests.
Authenticate a user
Authenticate with your credentials to access protected endpoints in the Argentine Rock Legends API.
Request Body
Responses
Authentication Successful
You have been successfully authenticated.
Response Details
The response includes:
- Your user information
- Authentication tokens (JWT token and API key)
- Token expiration information
Important: Store these credentials securely and include them in subsequent API requests.
Using Icons with vitepress-plugin-group-icons
vitepress-plugin-group-icons is a separate plugin that must be installed manually. It only loads icons referenced in Markdown files, so since vitepress-openapi renders code samples via Vue components, you need to instruct the plugin to preload the icons you use:
import { defineConfigWithTheme } from 'vitepress'
import { groupIconVitePlugin } from 'vitepress-plugin-group-icons'
export default defineConfigWithTheme({
// Your VitePress configuration...
vite: {
plugins: [
groupIconVitePlugin({
customIcon: {
curl: 'simple-icons:curl', // Custom icon for curl.
},
defaultLabels: [ // Preload icons for specific labels.
'curl',
'.ts',
'.js',
'.py',
'.php',
],
}),
],
},
})