DOCSEARCHbyAlgolia
Submit Docs

docusaurus-openapi Documentation

website·Indexed 32 days ago

https://docusaurus-openapi.tryingpan.dev/

API documentation and test schemas demonstrating OpenAPI 3.1 and JSON Schema 2020-12 implementations, including type unions, nested discriminators, and various request/response samples.

Tokens
71K
Snippets
471
Records
646
Agent score
55%

What's inside docusaurus-openapi

  1. Overview of Schema Expansion Demo API

    The Schema Expansion Demo API (Version 1.0.0) is designed to test and exercise configurable schema expansion controls. It features endpoints that return deeply nested envelope-wrapped payloads (typically structured as { status, meta, data }), where the primary data fields are located several levels deep under the data property. This allows developers to verify that the expansion pill controls in the documentation can reveal nested fields without requiring manual navigation.

  2. Overview of Docusaurus OpenAPI Docs

    The docusaurus-plugin-openapi-docs package extends the Docusaurus CLI to generate MDX files from OpenAPI specifications (Swagger 2.0 and OpenAPI 3.x). When paired with the docusaurus-theme-openapi-docs theme, it renders professional API reference documentation. The generated MDX is fully compatible with @docusaurus/plugin-content-docs.

  3. Comment object schema

    The Comment object represents a user comment and supports nested replies. It contains metadata about the comment's creation and updates, the author's identity, and the comment text.
    {
  "createdAt": "2024-07-29T15:51:28.071Z",
  "updatedAt": "2024-07-29T15:51:28.071Z",
  "id": 0,
  "author": "string",
  "body": "string",
  "replies": [
    null
  ]
}

  7. Handle intentional empty object schemas in OpenAPI

    To ensure a renderer displays an object shape rather than hiding it when no properties are defined, use an explicit empty object schema by defining type: object with an empty properties: {} block. This is useful for maintaining the visual structure of the API documentation when a field is intended to be an object but currently has no defined keys.
    type: object
properties:
  metadata:
    type: object
    properties: {}
  name:
    type: string

  8. Import and use generated schema MDX files as components

    Docusaurus allows you to import generated *.schema.mdx files (created by docusaurus-openapi-docs using the schema.mustache template) and use them as React components within your documentation pages. This is useful for referencing specific API schemas within larger supporting documentation.
    import PetSchema from './petstore/schemas/pet.schema.mdx';

<PetSchema />

  9. Handle Petstore store event callbacks

    When a subscribed event occurs, the Petstore API sends a callback to the registered callbackUrl with the event name as a query parameter (e.g., ?event=orderInProgress).

    The callback request body (application/json or application/xml) contains:

    • orderId (string): The ID of the order.
    • timestamp (string, date-time): The time the event occurred.
    • status (string): The status of the order (e.g., inProgress).

  10. Render enum parameters as dropdowns using allOf

    To ensure an API parameter renders as a dropdown or combobox in the documentation UI rather than a text input, wrap the enum reference within an allOf array in the parameter schema. This is particularly useful when the parameter is nullable or requires combined schema definitions.
    # Parameter definition
name: status
in: query
schema:
  nullable: true
  allOf:
    - $ref: '#/components/schemas/TaskStatus'

# Referenced Schema
components:
  schemas:
    TaskStatus:
      type: string
      enum: [Pending, InProgress, Completed, Cancelled]

  11. Bootstrap a new Docusaurus site with OpenAPI docs

    Use the create-docusaurus-openapi-docs CLI to quickly bootstrap a Docusaurus v3 site (classic theme) pre-configured with the OpenAPI plugin and theme.
    npx create-docusaurus-openapi-docs my-website
cd my-website
yarn start

  12. Create multiple users using the Petstore API

    To create a list of users, send a POST request to https://petstore.swagger.io/v2/user/createWithArray. The request body must be an array of user objects with a content type of application/json.

    User Object Requirements:

    • username: String, minimum 4 characters.
    • firstName: Non-empty string.
    • lastName: Non-empty string.
    • email: Valid email address string.
    • password: String, minimum 8 characters, must contain a mix of upper and lower case letters and digits (Regex: /(?=.*[a-z])(?=.*[A-Z])(?=.*[0-9])/).
    • phone: International format string (Regex: /^\+(?:[0-9]-?){6,14}[0-9]$/).
    • userStatus: Integer (int32).
    • pet: An object containing pet details, including a petType object with a huntingSkill (Possible values: clueless, lazy, adventurous, aggressive; Default: lazy).
    import http.client
import json

conn = http.client.HTTPSConnection("petstore.swagger.io")
payload = json.dumps([
  {
    "pet": {
      "category": {
        "name": "string",
        "sub": {
          "prop1": "string"
        }
      },
      "name": "Guru",
      "photoUrls": [
        "string"
      ],
      "tags": [
        {
          "name": "string"
        }
      ],
      "status": "available",
      "petType": {
        "huntingSkill": "adventurous"
      }
    },
    "username": "John78",
    "firstName": "John",
    "lastName": "Smith",
    "email": "john.smith@example.com",
    "password": "drowssaP123",
    "phone": "+1-202-555-0192",
    "userStatus": 0
  }
])
headers = {
  'Content-Type': 'application/json'
}
conn.request("POST", "/v2/user/createWithArray", payload, headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))