Operation Badges

Each operation can have different badges that indicate its state, for example if it is deprecated, the operation id, etc. The available badges are:

deprecated
operationId

By default, only the deprecated badge is shown, as appropriate. You can customize the operation badges using the useTheme({ operation: { badges: string[] }) function. The order in which you set the badges is the order in which they will be displayed.

markdown

---
aside: false
outline: false
title: vitepress-openapi
---

<script setup lang="ts">
import { useData } from 'vitepress'
import { useTheme } from 'vitepress-openapi'

const { isDark } = useData()

useTheme({
    operation: {
        badges: ['deprecated', 'operationId'],
    },
})
</script>

<OASpec :isDark="isDark" />

Example

v1.0.0

Argentine Rock Legends

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!

Placeholder image

Contact

Enzo Notario/hi@enzonotario.me

Servers

https://stoplight.io/mocks/enzonotario/argentine-rock/122547792Mock Server

Artists

Everything about Argentine Rock artists

Operations

GET/api/v1/artists POST/api/v1/artists GET/api/v1/artists/{artistId}PUT/api/v1/artists/{artistId}DELETE/api/v1/artists/{artistId}GET/api/v1/artists/{artistId}/albums POST/api/v1/artists/{artistId}/albums

ID: createArtist

Add a new artist

POST

/api/v1/artists

Add a new legendary Argentine Rock artist. Make sure they truly deserve the title!

Authorizations

bearerAuth

TypeHTTP (bearer)

apiKeyHeader

TypeAPI Key (header: X-API-Key)

Request Body

Use example

JSON

{

"id": 1,

"name": "Charly García",

"description": "One of the most influential rock musicians in Argentine history.",

"image": "https://cdn.rock-legends.com/photos/charly.jpg",

"band": "Sui Generis"

}

Responses

Created

Content-Type

application/json

Use example

JSON

{

"id": 1,

"name": "Charly García",

"description": "One of the most influential rock musicians in Argentine history.",

"image": "https://cdn.rock-legends.com/photos/charly.jpg",

"band": "Sui Generis"

}

POST

/api/v1/artists

Samples

Bruno

post {
  url: https://stoplight.io/mocks/enzonotario/argentine-rock/122547792/api/v1/artists
}

headers {
  Content-Type: application/json
}

cURL

curl -X POST \
'https://stoplight.io/mocks/enzonotario/argentine-rock/122547792/api/v1/artists' \
 -H "Content-Type: application/json"

JavaScript

fetch('https://stoplight.io/mocks/enzonotario/argentine-rock/122547792/api/v1/artists', {method:'POST',headers:{'Content-Type':'application/json'}})
  .then(response => response.json())
  .then(data => console.log(data));

PHP

<?php
$url = 'https://stoplight.io/mocks/enzonotario/argentine-rock/122547792/api/v1/artists';
$method = 'POST';
$headers = [
    'Content-Type' => 'application/json',
];

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, $method);
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);

$response = curl_exec($ch);
curl_close($ch);

echo $response;
?>

Python

import requests

url = 'https://stoplight.io/mocks/enzonotario/argentine-rock/122547792/api/v1/artists'

headers = {
    'Content-Type': 'application/json'
}

response = requests.post(url, headers=headers)
print(response.json())

ID: getArtist

Get an artist

GET

/api/v1/artists/{artistId}

Learn more about a specific Argentine Rock artist and their legacy.

Parameters

Path Parameters

artistId*

Typeinteger

Required

Example1

formatint64

Responses

Artist Found

Content-Type

application/json

Use example

JSON

{

"id": 1,

"name": "Charly García",

"description": "One of the most influential rock musicians in Argentine history.",

"image": "https://cdn.rock-legends.com/photos/charly.jpg",

"band": "Sui Generis"

}

GET

/api/v1/artists/{artistId}

Samples

Bruno

get {
  url: https://stoplight.io/mocks/enzonotario/argentine-rock/122547792/api/v1/artists/1
}

headers {
  Content-Type: application/json
}

cURL

curl -X GET \
'https://stoplight.io/mocks/enzonotario/argentine-rock/122547792/api/v1/artists/1' \
 -H "Content-Type: application/json"

JavaScript

fetch('https://stoplight.io/mocks/enzonotario/argentine-rock/122547792/api/v1/artists/1', {headers:{'Content-Type':'application/json'}})
  .then(response => response.json())
  .then(data => console.log(data));

PHP

<?php
$url = 'https://stoplight.io/mocks/enzonotario/argentine-rock/122547792/api/v1/artists/1';
$method = 'GET';
$headers = [
    'Content-Type' => 'application/json',
];

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, $method);
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);

$response = curl_exec($ch);
curl_close($ch);

echo $response;
?>

Python

import requests

url = 'https://stoplight.io/mocks/enzonotario/argentine-rock/122547792/api/v1/artists/1'

headers = {
    'Content-Type': 'application/json'
}

response = requests.get(url, headers=headers)
print(response.json())

ID: updateArtist

Update an artist

PUT

/api/v1/artists/{artistId}

Update the information of a legendary Argentine Rock artist. Make sure to provide accurate data.

Authorizations

bearerAuth

TypeHTTP (bearer)

apiKeyHeader

TypeAPI Key (header: X-API-Key)

Parameters

Path Parameters

artistId*

Typeinteger

Required

Example1

formatint64

Request Body

Use example

JSON

{

"id": 1,

"name": "Charly García",

"description": "One of the most influential rock musicians in Argentine history.",

"image": "https://cdn.rock-legends.com/photos/charly.jpg",

"band": "Sui Generis"

}

Responses

Content-Type

application/json

Use example

JSON

{

"id": 1,

"name": "Charly García",

"description": "One of the most influential rock musicians in Argentine history.",

"image": "https://cdn.rock-legends.com/photos/charly.jpg",

"band": "Sui Generis"

}

PUT

/api/v1/artists/{artistId}

Samples

Bruno

put {
  url: https://stoplight.io/mocks/enzonotario/argentine-rock/122547792/api/v1/artists/1
}

headers {
  Content-Type: application/json
}

cURL

curl -X PUT \
'https://stoplight.io/mocks/enzonotario/argentine-rock/122547792/api/v1/artists/1' \
 -H "Content-Type: application/json"

JavaScript

fetch('https://stoplight.io/mocks/enzonotario/argentine-rock/122547792/api/v1/artists/1', {method:'PUT',headers:{'Content-Type':'application/json'}})
  .then(response => response.json())
  .then(data => console.log(data));

PHP

<?php
$url = 'https://stoplight.io/mocks/enzonotario/argentine-rock/122547792/api/v1/artists/1';
$method = 'PUT';
$headers = [
    'Content-Type' => 'application/json',
];

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, $method);
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);

$response = curl_exec($ch);
curl_close($ch);

echo $response;
?>

Python

import requests

url = 'https://stoplight.io/mocks/enzonotario/argentine-rock/122547792/api/v1/artists/1'

headers = {
    'Content-Type': 'application/json'
}

response = requests.put(url, headers=headers)
print(response.json())

Deprecated

ID: deleteArtist

Delete an artist

DELETE

/api/v1/artists/{artistId}

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.

Authorizations

bearerAuth

TypeHTTP (bearer)

apiKeyHeader

TypeAPI Key (header: X-API-Key)

Parameters

Path Parameters

artistId*

Typeinteger

Required

Example1

formatint64

Responses

Bad Request

Content-Type

application/json

Use example

JSON

{

"type": "https://example.com/errors/generic-error",

"title": "Something went wrong here.",

"status": 403,

"detail": "Unfortunately, we can’t provide further information."

}

DELETE

/api/v1/artists/{artistId}

Samples

Bruno

delete {
  url: https://stoplight.io/mocks/enzonotario/argentine-rock/122547792/api/v1/artists/1
}

headers {
  Content-Type: application/json
}

cURL

curl -X DELETE \
'https://stoplight.io/mocks/enzonotario/argentine-rock/122547792/api/v1/artists/1' \
 -H "Content-Type: application/json"

JavaScript

fetch('https://stoplight.io/mocks/enzonotario/argentine-rock/122547792/api/v1/artists/1', {method:'DELETE',headers:{'Content-Type':'application/json'}})
  .then(response => response.json())
  .then(data => console.log(data));

PHP

<?php
$url = 'https://stoplight.io/mocks/enzonotario/argentine-rock/122547792/api/v1/artists/1';
$method = 'DELETE';
$headers = [
    'Content-Type' => 'application/json',
];

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, $method);
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);

$response = curl_exec($ch);
curl_close($ch);

echo $response;
?>

Python

import requests

url = 'https://stoplight.io/mocks/enzonotario/argentine-rock/122547792/api/v1/artists/1'

headers = {
    'Content-Type': 'application/json'
}

response = requests.delete(url, headers=headers)
print(response.json())

ID: getAllAlbums

Get all albums

GET

/api/v1/artists/{artistId}/albums

Get a list of all albums from a legendary Argentine Rock artist.

Parameters

Path Parameters

artistId*

Typeinteger

Required

Example1

formatint64

Query Parameters

limit

The number of items to return

Typeinteger

Examples

102050

formatint64

default10

offset

The number of items to skip before starting to collect the result set

Typeinteger

Examples

123456

formatint64

default0

Responses

Content-Type

application/json

Use example

JSON

{

"data": [

{

"id": 1,

"name": "La Máquina de Hacer Pájaros",

"year": 1976,

"image": "https://cdn.rock-legends.com/photos/la-maquina.jpg"

}

"meta": {

"limit": 10,

"offset": 0,

"total": 100,

"next": "/artists?limit=10&offset=10"

}

GET

/api/v1/artists/{artistId}/albums

Samples

Bruno

get {
  url: https://stoplight.io/mocks/enzonotario/argentine-rock/122547792/api/v1/artists/1/albums?limit=10&offset=1
}

headers {
  Content-Type: application/json
}

cURL

curl -X GET \
'https://stoplight.io/mocks/enzonotario/argentine-rock/122547792/api/v1/artists/1/albums?limit=10&offset=1' \
 -H "Content-Type: application/json"

JavaScript

fetch('https://stoplight.io/mocks/enzonotario/argentine-rock/122547792/api/v1/artists/1/albums?limit=10&offset=1', {headers:{'Content-Type':'application/json'}})
  .then(response => response.json())
  .then(data => console.log(data));

PHP

<?php
$url = 'https://stoplight.io/mocks/enzonotario/argentine-rock/122547792/api/v1/artists/1/albums';
$method = 'GET';
$headers = [
    'Content-Type' => 'application/json',
];
$query = http_build_query([
    'limit' => '10',
    'offset' => '1',
]);

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url . '?' . $query);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, $method);
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);

$response = curl_exec($ch);
curl_close($ch);

echo $response;
?>

Python

import requests

url = 'https://stoplight.io/mocks/enzonotario/argentine-rock/122547792/api/v1/artists/1/albums'
params = {
    'limit': 10,
    'offset': 1
}
headers = {
    'Content-Type': 'application/json'
}

response = requests.get(url, params=params, headers=headers)
print(response.json())

ID: createAlbum

Add a new album

POST

/api/v1/artists/{artistId}/albums

Add a new album to a legendary Argentine Rock artist. Make sure it’s a masterpiece!

Authorizations

bearerAuth

TypeHTTP (bearer)

apiKeyHeader

TypeAPI Key (header: X-API-Key)

Parameters

Path Parameters

artistId*

Typeinteger

Required

Example1

formatint64

Request Body

Use example

JSON

{

"id": 1,

"name": "La Máquina de Hacer Pájaros",

"year": 1976,

"image": "https://cdn.rock-legends.com/photos/la-maquina.jpg"

}

Responses

Created

Content-Type

application/json

Use example

JSON

{

"id": 1,

"name": "La Máquina de Hacer Pájaros",

"year": 1976,

"image": "https://cdn.rock-legends.com/photos/la-maquina.jpg"

}

POST

/api/v1/artists/{artistId}/albums

Samples

Bruno

post {
  url: https://stoplight.io/mocks/enzonotario/argentine-rock/122547792/api/v1/artists/1/albums
}

headers {
  Content-Type: application/json
}

cURL

curl -X POST \
'https://stoplight.io/mocks/enzonotario/argentine-rock/122547792/api/v1/artists/1/albums' \
 -H "Content-Type: application/json"

JavaScript

fetch('https://stoplight.io/mocks/enzonotario/argentine-rock/122547792/api/v1/artists/1/albums', {method:'POST',headers:{'Content-Type':'application/json'}})
  .then(response => response.json())
  .then(data => console.log(data));

PHP

<?php
$url = 'https://stoplight.io/mocks/enzonotario/argentine-rock/122547792/api/v1/artists/1/albums';
$method = 'POST';
$headers = [
    'Content-Type' => 'application/json',
];

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, $method);
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);

$response = curl_exec($ch);
curl_close($ch);

echo $response;
?>

Python

import requests

url = 'https://stoplight.io/mocks/enzonotario/argentine-rock/122547792/api/v1/artists/1/albums'

headers = {
    'Content-Type': 'application/json'
}

response = requests.post(url, headers=headers)
print(response.json())

Authentication

Some endpoints are public, but some require authentication. We provide all the required endpoints to create an account and authorize yourself.

Operations

POST/api/v1/user/signup

ID: createUser

Create a user

POST

/api/v1/user/signup

Create a user account to access exclusive content about Argentine Rock legends.

Request Body

Use example

JSON

{

"name": "Carlos",

"email": "carlos@rock-legends.com",

"password": "i-love-rock"

}

Responses

Created

Content-Type

application/json

Use example

JSON

{

"id": 1,

"name": "Carlos",

"email": "carlos@rock-legends.com"

}

POST

/api/v1/user/signup

Samples

Bruno

post {
  url: https://stoplight.io/mocks/enzonotario/argentine-rock/122547792/api/v1/user/signup
}

headers {
  Content-Type: application/json
}

cURL

curl -X POST \
'https://stoplight.io/mocks/enzonotario/argentine-rock/122547792/api/v1/user/signup' \
 -H "Content-Type: application/json"

JavaScript

fetch('https://stoplight.io/mocks/enzonotario/argentine-rock/122547792/api/v1/user/signup', {method:'POST',headers:{'Content-Type':'application/json'}})
  .then(response => response.json())
  .then(data => console.log(data));

PHP

<?php
$url = 'https://stoplight.io/mocks/enzonotario/argentine-rock/122547792/api/v1/user/signup';
$method = 'POST';
$headers = [
    'Content-Type' => 'application/json',
];

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, $method);
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);

$response = curl_exec($ch);
curl_close($ch);

echo $response;
?>

Python

import requests

url = 'https://stoplight.io/mocks/enzonotario/argentine-rock/122547792/api/v1/user/signup'

headers = {
    'Content-Type': 'application/json'
}

response = requests.post(url, headers=headers)
print(response.json())

Custom Prefix

You can also customize the prefix of the badges by setting the operation.badgePrefix.{badgeName} key in the i18n messages. For example, in your .vitepress/theme/index.ts, before calling theme.enhanceApp({ app }), you can set the following:

typescript

import { locales, theme, useTheme } from 'vitepress-openapi'
import DefaultTheme from 'vitepress/theme'
import 'vitepress-openapi/dist/style.css'

export default {
    extends: DefaultTheme,
    enhanceApp({ app }) {
        useTheme({
            i18n: {
                messages: {
                    en: {
                        ...locales.en,
                        'operation.badgePrefix.operationId': 'Operation ID: ',
                    },
                    es: {
                        ...locales.es,
                        'operation.badgePrefix.operationId': 'ID de operación: ',
                    },
                },
            },
        })

        // Use the theme.
        theme.enhanceApp({ app })
    },
}

/artists

/{artistId}

/user/signup

/artists

/artists/{artistId}

/artists/{artistId}/albums

/user/signup

Operation Badges ​

Argentine Rock Legends​

Resources

Markdown Support

Contact​

Servers​

Artists​

Operations​

Add a new artist​

Authorizations​

Request Body​

Responses​

Samples​

Get an artist​

Parameters​

Path Parameters

Responses​

Samples​

Update an artist​

Authorizations​

Parameters​

Path Parameters

Request Body​

Responses​

Samples​

Delete an artist​

Authorizations​

Parameters​

Path Parameters

Responses​

Samples​

Get all albums​

Parameters​

Path Parameters

Query Parameters

Responses​

Samples​

Add a new album​

Authorizations​

Parameters​

Path Parameters

Request Body​

Responses​

Samples​

Authentication​

Operations​

Create a user​

Request Body​

Responses​

Samples​

Custom Prefix ​

Operation Badges

Argentine Rock Legends

Contact

Servers

Artists

Operations

Add a new artist

Authorizations

Request Body

Responses

Samples

Get an artist

Parameters

Responses

Samples

Update an artist

Authorizations

Parameters

Request Body

Responses

Samples

Delete an artist

Authorizations

Parameters

Responses

Samples

Get all albums

Parameters

Responses

Samples

Add a new album

Authorizations

Parameters

Request Body

Responses

Samples

Authentication

Operations

Create a user

Request Body

Responses

Samples

Custom Prefix