diff --git a/.github/workflows/validate-scalar-configuration.yml b/.github/workflows/validate-scalar-configuration.yml new file mode 100644 index 0000000..1339989 --- /dev/null +++ b/.github/workflows/validate-scalar-configuration.yml @@ -0,0 +1,32 @@ +name: Validate Scalar Configuration + +on: + # push to main + push: + branches: + - main + paths: + - "scalar.config.json" + - "docs/**" + # pull requests + pull_request: + paths: + - "scalar.config.json" + - "docs/**" + +jobs: + validate: + name: Validate scalar.config.json + runs-on: ubuntu-latest + + steps: + - name: Checkout repository + uses: actions/checkout@v6 + + - name: Setup Node.js + uses: actions/setup-node@v6 + with: + node-version: "24" + + - name: Validate + run: npx @scalar/cli@latest project check-config diff --git a/LICENSE b/LICENSE index 5e69402..05ee3dd 100644 --- a/LICENSE +++ b/LICENSE @@ -1,6 +1,6 @@ MIT License -Copyright (c) 2025 Scalar +Copyright (c) 2023-present Scalar Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal @@ -18,4 +18,4 @@ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE -SOFTWARE. \ No newline at end of file +SOFTWARE. diff --git a/README.md b/README.md index f04778f..a4375e8 100644 --- a/README.md +++ b/README.md @@ -5,11 +5,11 @@ [![Twitter](https://img.shields.io/twitter/follow/scalar)](https://x.com/scalar) [![Discord](https://img.shields.io/discord/1135330207960678410?style=flat&color=5865F2)](https://discord.gg/scalar) -Welcome to the Scalar Docs starter kit! This project provides you with a complete foundation to create beautiful, interactive API documentation using Scalar's powerful documentation platform. +Welcome to the Scalar Docs Starter Kit! Deploy Markdown and OpenAPI documents from GitHub. ## Preview -Use the Scalar CLI to render a live preview of your project locally: +Use the [Scalar CLI](https://scalar.com/tools/cli/getting-started) to render a live preview of your project locally: ```bash npx @scalar/cli project preview @@ -27,6 +27,10 @@ npx @scalar/cli project check-config This will verify that your `scalar.config.json` file contains valid settings and help identify any configuration issues. +### GitHub Action + +This repository includes a GitHub Action workflow that automatically validates the configuration on every push and pull request. See [`.github/workflows/validate-scalar-configuration.yml`](./.github/workflows/validate-scalar-configuration.yml). + ## Project Structure ``` diff --git a/docs/api-reference/openapi.yaml b/docs/api-reference/openapi.yaml index 4535858..4fc6d3c 100644 --- a/docs/api-reference/openapi.yaml +++ b/docs/api-reference/openapi.yaml @@ -48,11 +48,11 @@ info: > You can now use markdown alerts in your descriptions. - version: 0.5.7 + version: 0.5.12 contact: name: Scalar Support url: https://scalar.com - email: marc@scalar.com + email: support@scalar.com license: name: MIT url: https://opensource.org/license/MIT @@ -61,15 +61,16 @@ externalDocs: url: https://github.com/scalar/scalar servers: - url: https://galaxy.scalar.com - - url: '{protocol}://void.scalar.com/{path}' + - url: "{protocol}://void.scalar.com/{path}" description: Responds with your request data variables: protocol: enum: - https + - http default: https path: - default: '' + default: "" security: - bearerAuth: [] - basicAuth: [] @@ -78,42 +79,49 @@ security: - apiKeyCookie: [] - oAuth2: [] - openIdConnect: [] +x-speakeasy-webhooks: + security: + type: signature + headerName: x-signature + signatureTextEncoding: base64 + algorithm: hmac-sha256 tags: - name: Authentication - description: - Some endpoints are public, but some require authentication. We provide - all the required endpoints to create an account and authorize yourself. + description: Some endpoints are public, but some require authentication. We + provide all the required endpoints to create an account and authorize + yourself. - name: Planets description: Everything about planets - name: Celestial Bodies description: Celestial bodies are the planets and satellites in the Scalar Galaxy. paths: - '/planets': + /planets: get: tags: - Planets summary: Get all planets - description: It's easy to say you know them all, but do you really? Retrieve all the planets and check whether you missed one. + description: It's easy to say you know them all, but do you really? Retrieve all + the planets and check whether you missed one. operationId: getAllData security: - {} parameters: - - $ref: '#/components/parameters/limit' - - $ref: '#/components/parameters/offset' + - $ref: "#/components/parameters/limit" + - $ref: "#/components/parameters/offset" responses: - '200': + "200": description: OK headers: X-Request-ID: - $ref: '#/components/headers/X-Request-ID' + $ref: "#/components/headers/X-Request-ID" X-Pagination-Total: - $ref: '#/components/headers/X-Pagination-Total' + $ref: "#/components/headers/X-Pagination-Total" X-Pagination-Page: - $ref: '#/components/headers/X-Pagination-Page' + $ref: "#/components/headers/X-Pagination-Page" X-Pagination-Per-Page: - $ref: '#/components/headers/X-Pagination-Per-Page' + $ref: "#/components/headers/X-Pagination-Per-Page" X-Cache-Control: - $ref: '#/components/headers/X-Cache-Control' + $ref: "#/components/headers/X-Cache-Control" content: application/json: schema: @@ -123,8 +131,8 @@ paths: data: type: array items: - $ref: '#/components/schemas/Planet' - - $ref: '#/components/schemas/PaginatedResource' + $ref: "#/components/schemas/Planet" + - $ref: "#/components/schemas/PaginatedResource" application/xml: schema: allOf: @@ -135,165 +143,864 @@ paths: data: type: array items: - $ref: '#/components/schemas/Planet' - - $ref: '#/components/schemas/PaginatedResource' + $ref: "#/components/schemas/Planet" + - $ref: "#/components/schemas/PaginatedResource" + x-codeSamples: + - label: csharp + lang: csharp + source: |- + using Scalar.GalaxyCsharp; + + var sdk = new GalaxyCsharp(); + + var res = await sdk.Planets.GetAllDataAsync( + limit: 10, + offset: 0 + ); + + // handle response + - label: typescript + lang: typescript + source: |- + import { GalaxyTypescript } from "@scalar/galaxy-typescript"; + + const galaxyTypescript = new GalaxyTypescript(); + + async function run() { + const result = await galaxyTypescript.planets.getAllData({}); + + console.log(result); + } + + run(); post: tags: - Planets summary: Create a planet - description: Time to play god and create a new planet. What do you think? Ah, don't think too much. What could go wrong anyway? + description: Time to play god and create a new planet. What do you think? Ah, + don't think too much. What could go wrong anyway? operationId: createPlanet callbacks: planetCreated: - '{$request.body#/successCallbackUrl}': + "{$request.body#/successCallbackUrl}": post: requestBody: description: Information about the newly created planet content: application/json: schema: - $ref: '#/components/schemas/Planet' + $ref: "#/components/schemas/Planet" responses: - '200': + "200": description: Your server returns this code if it accepts the callback - '204': - description: Your server should return this HTTP status code if no longer interested in further updates - '{$request.body#/failureCallbackUrl}': + "204": + description: Your server should return this HTTP status code if no longer + interested in further updates + planetCreationFailed: + "{$request.body#/failureCallbackUrl}": post: requestBody: description: Information about which fields failed to validate content: application/json: schema: - $ref: '#/components/schemas/Planet' + $ref: "#/components/schemas/Planet" responses: - '200': - description: Your server returns this code if it accepts the callback + "200": + description: Your server returns this code if it accepts the failure callback + notification planetExploded: - '{$request.body#/successCallbackUrl}': + "{$request.body#/successCallbackUrl}": post: requestBody: description: Information about the newly exploded planet content: application/json: schema: - $ref: '#/components/schemas/Planet' + $ref: "#/components/schemas/Planet" responses: - '200': - description: Your server returns this code if it accepts the callback + "200": + description: Your server returns this code if it accepts the planet explosion + callback notification requestBody: description: Planet content: application/json: schema: - $ref: '#/components/schemas/Planet' + $ref: "#/components/schemas/Planet" application/xml: schema: - $ref: '#/components/schemas/Planet' + $ref: "#/components/schemas/Planet" responses: - '201': + "201": description: Created headers: X-Request-ID: - $ref: '#/components/headers/X-Request-ID' + $ref: "#/components/headers/X-Request-ID" Location: - $ref: '#/components/headers/Location' + $ref: "#/components/headers/Location" X-Processing-Time: - $ref: '#/components/headers/X-Processing-Time' + $ref: "#/components/headers/X-Processing-Time" content: application/json: schema: - $ref: '#/components/schemas/Planet' + $ref: "#/components/schemas/Planet" application/xml: schema: - $ref: '#/components/schemas/Planet' - '400': - $ref: '#/components/responses/BadRequest' - '403': - $ref: '#/components/responses/Forbidden' - '/planets/{planetId}': + $ref: "#/components/schemas/Planet" + "400": + $ref: "#/components/responses/BadRequest" + "403": + $ref: "#/components/responses/Forbidden" + x-codeSamples: + - label: csharp + lang: csharp + source: >- + using Scalar.GalaxyCsharp; + + using Scalar.GalaxyCsharp.Models.Components; + + using System; + + using System.Collections.Generic; + + + var sdk = new GalaxyCsharp(); + + + PlanetInput req = new PlanetInput() { + Name = "Mars", + Description = "The red planet", + Type = Scalar.GalaxyCsharp.Models.Components.Type.Terrestrial, + HabitabilityIndex = 0.68F, + PhysicalProperties = new PhysicalProperties() { + Mass = 0.107F, + Radius = 0.532F, + Gravity = 0.378F, + Temperature = new Temperature() { + Min = 130F, + Max = 308F, + Average = 210F, + }, + }, + Atmosphere = new List() { + new Atmosphere() { + Compound = "CO2", + Percentage = 95.3F, + }, + }, + DiscoveredAt = System.DateTime.Parse("1610-01-07T00:00:00Z"), + Image = "https://cdn.scalar.com/photos/mars.jpg", + Satellites = new List() { + new SatelliteInput() { + Name = "Phobos", + Description = "Phobos is the larger and innermost of the two moons of Mars.", + Diameter = 22.2F, + Type = SatelliteType.Moon, + Orbit = new Orbit() { + Planet = new Planet() { + Id = 1, + Name = "Mars", + Description = "The red planet", + Type = Scalar.GalaxyCsharp.Models.Components.Type.Terrestrial, + HabitabilityIndex = 0.68F, + PhysicalProperties = new PhysicalProperties() { + Mass = 0.107F, + Radius = 0.532F, + Gravity = 0.378F, + Temperature = new Temperature() { + Min = 130F, + Max = 308F, + Average = 210F, + }, + }, + Atmosphere = new List() { + new Atmosphere() { + Compound = "CO2", + Percentage = 95.3F, + }, + }, + DiscoveredAt = System.DateTime.Parse("1610-01-07T00:00:00Z"), + Image = "https://cdn.scalar.com/photos/mars.jpg", + Satellites = new List() { + new Satellite() { + Id = 1, + Name = "Phobos", + Description = "Phobos is the larger and innermost of the two moons of Mars.", + Diameter = 22.2F, + Type = SatelliteType.Moon, + Orbit = new Orbit() { + Planet = new Planet() { + Id = 1, + Name = "Mars", + Description = "The red planet", + Type = Scalar.GalaxyCsharp.Models.Components.Type.Terrestrial, + HabitabilityIndex = 0.68F, + PhysicalProperties = new PhysicalProperties() { + Mass = 0.107F, + Radius = 0.532F, + Gravity = 0.378F, + Temperature = new Temperature() { + Min = 130F, + Max = 308F, + Average = 210F, + }, + }, + Atmosphere = new List() { + new Atmosphere() { + Compound = "CO2", + Percentage = 95.3F, + }, + }, + DiscoveredAt = System.DateTime.Parse("1610-01-07T00:00:00Z"), + Image = "https://cdn.scalar.com/photos/mars.jpg", + Creator = new User() { + Id = 1, + Name = "Marc", + }, + Tags = new List() { + "solar-system", + "rocky", + "explored", + }, + LastUpdated = System.DateTime.Parse("2024-01-15T14:30:00Z"), + SuccessCallbackUrl = "https://example.com/webhook", + FailureCallbackUrl = "https://example.com/webhook", + }, + OrbitalPeriod = 0.319F, + Distance = 9376F, + }, + }, + }, + Creator = new User() { + Id = 1, + Name = "Marc", + }, + Tags = new List() { + "solar-system", + "rocky", + "explored", + }, + LastUpdated = System.DateTime.Parse("2024-01-15T14:30:00Z"), + SuccessCallbackUrl = "https://example.com/webhook", + FailureCallbackUrl = "https://example.com/webhook", + }, + OrbitalPeriod = 0.319F, + Distance = 9376F, + }, + }, + }, + Creator = new UserInput() { + Name = "Marc", + }, + Tags = new List() { + "solar-system", + "rocky", + "explored", + }, + SuccessCallbackUrl = "https://example.com/webhook", + FailureCallbackUrl = "https://example.com/webhook", + }; + + + var res = await sdk.Planets.CreatePlanetJsonAsync(req); + + + // handle response + - label: typescript + lang: typescript + source: >- + import { GalaxyTypescript } from "@scalar/galaxy-typescript"; + + + const galaxyTypescript = new GalaxyTypescript(); + + + async function run() { + const result = await galaxyTypescript.planets.createPlanetJson({ + name: "Mars", + description: "The red planet", + type: "terrestrial", + habitabilityIndex: 0.68, + physicalProperties: { + mass: 0.107, + radius: 0.532, + gravity: 0.378, + temperature: { + min: 130, + max: 308, + average: 210, + }, + }, + atmosphere: [ + { + compound: "CO2", + percentage: 95.3, + }, + ], + discoveredAt: new Date("1610-01-07T00:00:00Z"), + image: "https://cdn.scalar.com/photos/mars.jpg", + satellites: [ + { + name: "Phobos", + description: "Phobos is the larger and innermost of the two moons of Mars.", + diameter: 22.2, + type: "moon", + orbit: { + planet: { + id: 1, + name: "Mars", + description: "The red planet", + type: "terrestrial", + habitabilityIndex: 0.68, + physicalProperties: { + mass: 0.107, + radius: 0.532, + gravity: 0.378, + temperature: { + min: 130, + max: 308, + average: 210, + }, + }, + atmosphere: [ + { + compound: "CO2", + percentage: 95.3, + }, + ], + discoveredAt: new Date("1610-01-07T00:00:00Z"), + image: "https://cdn.scalar.com/photos/mars.jpg", + satellites: [ + { + id: 1, + name: "Phobos", + description: "Phobos is the larger and innermost of the two moons of Mars.", + diameter: 22.2, + type: "moon", + orbit: { + planet: { + id: 1, + name: "Mars", + description: "The red planet", + type: "terrestrial", + habitabilityIndex: 0.68, + physicalProperties: { + mass: 0.107, + radius: 0.532, + gravity: 0.378, + temperature: { + min: 130, + max: 308, + average: 210, + }, + }, + atmosphere: [ + { + compound: "CO2", + percentage: 95.3, + }, + ], + discoveredAt: new Date("1610-01-07T00:00:00Z"), + image: "https://cdn.scalar.com/photos/mars.jpg", + creator: { + id: 1, + name: "Marc", + }, + tags: [ + "solar-system", + "rocky", + "explored", + ], + lastUpdated: new Date("2024-01-15T14:30:00Z"), + successCallbackUrl: "https://example.com/webhook", + failureCallbackUrl: "https://example.com/webhook", + }, + orbitalPeriod: 0.319, + distance: 9376, + }, + }, + ], + creator: { + id: 1, + name: "Marc", + }, + tags: [ + "solar-system", + "rocky", + "explored", + ], + lastUpdated: new Date("2024-01-15T14:30:00Z"), + successCallbackUrl: "https://example.com/webhook", + failureCallbackUrl: "https://example.com/webhook", + }, + orbitalPeriod: 0.319, + distance: 9376, + }, + }, + ], + creator: { + name: "Marc", + }, + tags: [ + "solar-system", + "rocky", + "explored", + ], + successCallbackUrl: "https://example.com/webhook", + failureCallbackUrl: "https://example.com/webhook", + }); + + console.log(result); + } + + + run(); + /planets/{planetId}: get: tags: - Planets summary: Get a planet - description: You'll better learn a little bit more about the planets. It might come in handy once space travel is available for everyone. + description: You'll better learn a little bit more about the planets. It might + come in handy once space travel is available for everyone. operationId: getPlanet security: - {} parameters: - - $ref: '#/components/parameters/planetId' + - $ref: "#/components/parameters/planetId" responses: - '200': + "200": description: Planet Found headers: X-Request-ID: - $ref: '#/components/headers/X-Request-ID' + $ref: "#/components/headers/X-Request-ID" ETag: - $ref: '#/components/headers/ETag' + $ref: "#/components/headers/ETag" Last-Modified: - $ref: '#/components/headers/Last-Modified' + $ref: "#/components/headers/Last-Modified" X-Cache-Control: - $ref: '#/components/headers/X-Cache-Control' + $ref: "#/components/headers/X-Cache-Control" content: application/json: schema: - $ref: '#/components/schemas/Planet' + $ref: "#/components/schemas/Planet" application/xml: schema: - $ref: '#/components/schemas/Planet' - '404': - $ref: '#/components/responses/NotFound' + $ref: "#/components/schemas/Planet" + "404": + $ref: "#/components/responses/NotFound" + x-codeSamples: + - label: csharp + lang: csharp + source: |- + using Scalar.GalaxyCsharp; + + var sdk = new GalaxyCsharp(); + + var res = await sdk.Planets.GetPlanetAsync(planetId: 1); + + // handle response + - label: typescript + lang: typescript + source: |- + import { GalaxyTypescript } from "@scalar/galaxy-typescript"; + + const galaxyTypescript = new GalaxyTypescript(); + + async function run() { + const result = await galaxyTypescript.planets.getPlanet({ + planetId: 1, + }); + + console.log(result); + } + + run(); put: tags: - Planets summary: Update a planet - description: Sometimes you make mistakes, that's fine. No worries, you can update all planets. + description: Sometimes you make mistakes, that's fine. No worries, you can + update all planets. operationId: updatePlanet requestBody: description: New information about the planet content: application/json: schema: - $ref: '#/components/schemas/Planet' + $ref: "#/components/schemas/Planet" application/xml: schema: - $ref: '#/components/schemas/Planet' + $ref: "#/components/schemas/Planet" parameters: - - $ref: '#/components/parameters/planetId' + - $ref: "#/components/parameters/planetId" responses: - '200': - description: OK + "200": + description: Planet updated successfully content: application/json: schema: - $ref: '#/components/schemas/Planet' + $ref: "#/components/schemas/Planet" application/xml: schema: - $ref: '#/components/schemas/Planet' - '400': - $ref: '#/components/responses/BadRequest' - '403': - $ref: '#/components/responses/Forbidden' - '404': - $ref: '#/components/responses/NotFound' + $ref: "#/components/schemas/Planet" + "400": + $ref: "#/components/responses/BadRequest" + "403": + $ref: "#/components/responses/Forbidden" + "404": + $ref: "#/components/responses/NotFound" + x-codeSamples: + - label: csharp + lang: csharp + source: >- + using Scalar.GalaxyCsharp; + + using Scalar.GalaxyCsharp.Models.Components; + + using System; + + using System.Collections.Generic; + + + var sdk = new GalaxyCsharp(); + + + var res = await sdk.Planets.UpdatePlanetJsonAsync( + planetId: 1, + planet: new PlanetInput() { + Name = "Mars", + Description = "The red planet", + Type = Scalar.GalaxyCsharp.Models.Components.Type.Terrestrial, + HabitabilityIndex = 0.68F, + PhysicalProperties = new PhysicalProperties() { + Mass = 0.107F, + Radius = 0.532F, + Gravity = 0.378F, + Temperature = new Temperature() { + Min = 130F, + Max = 308F, + Average = 210F, + }, + }, + Atmosphere = new List() { + new Atmosphere() { + Compound = "CO2", + Percentage = 95.3F, + }, + }, + DiscoveredAt = System.DateTime.Parse("1610-01-07T00:00:00Z"), + Image = "https://cdn.scalar.com/photos/mars.jpg", + Satellites = new List() { + new SatelliteInput() { + Name = "Phobos", + Description = "Phobos is the larger and innermost of the two moons of Mars.", + Diameter = 22.2F, + Type = SatelliteType.Moon, + Orbit = new Orbit() { + Planet = new Planet() { + Id = 1, + Name = "Mars", + Description = "The red planet", + Type = Scalar.GalaxyCsharp.Models.Components.Type.Terrestrial, + HabitabilityIndex = 0.68F, + PhysicalProperties = new PhysicalProperties() { + Mass = 0.107F, + Radius = 0.532F, + Gravity = 0.378F, + Temperature = new Temperature() { + Min = 130F, + Max = 308F, + Average = 210F, + }, + }, + Atmosphere = new List() { + new Atmosphere() { + Compound = "CO2", + Percentage = 95.3F, + }, + }, + DiscoveredAt = System.DateTime.Parse("1610-01-07T00:00:00Z"), + Image = "https://cdn.scalar.com/photos/mars.jpg", + Satellites = new List() { + new Satellite() { + Id = 1, + Name = "Phobos", + Description = "Phobos is the larger and innermost of the two moons of Mars.", + Diameter = 22.2F, + Type = SatelliteType.Moon, + Orbit = new Orbit() { + Planet = new Planet() { + Id = 1, + Name = "Mars", + Description = "The red planet", + Type = Scalar.GalaxyCsharp.Models.Components.Type.Terrestrial, + HabitabilityIndex = 0.68F, + PhysicalProperties = new PhysicalProperties() { + Mass = 0.107F, + Radius = 0.532F, + Gravity = 0.378F, + Temperature = new Temperature() { + Min = 130F, + Max = 308F, + Average = 210F, + }, + }, + Atmosphere = new List() { + new Atmosphere() { + Compound = "CO2", + Percentage = 95.3F, + }, + }, + DiscoveredAt = System.DateTime.Parse("1610-01-07T00:00:00Z"), + Image = "https://cdn.scalar.com/photos/mars.jpg", + Creator = new User() { + Id = 1, + Name = "Marc", + }, + Tags = new List() { + "solar-system", + "rocky", + "explored", + }, + LastUpdated = System.DateTime.Parse("2024-01-15T14:30:00Z"), + SuccessCallbackUrl = "https://example.com/webhook", + FailureCallbackUrl = "https://example.com/webhook", + }, + OrbitalPeriod = 0.319F, + Distance = 9376F, + }, + }, + }, + Creator = new User() { + Id = 1, + Name = "Marc", + }, + Tags = new List() { + "solar-system", + "rocky", + "explored", + }, + LastUpdated = System.DateTime.Parse("2024-01-15T14:30:00Z"), + SuccessCallbackUrl = "https://example.com/webhook", + FailureCallbackUrl = "https://example.com/webhook", + }, + OrbitalPeriod = 0.319F, + Distance = 9376F, + }, + }, + }, + Creator = new UserInput() { + Name = "Marc", + }, + Tags = new List() { + "solar-system", + "rocky", + "explored", + }, + SuccessCallbackUrl = "https://example.com/webhook", + FailureCallbackUrl = "https://example.com/webhook", + } + ); + + + // handle response + - label: typescript + lang: typescript + source: >- + import { GalaxyTypescript } from "@scalar/galaxy-typescript"; + + + const galaxyTypescript = new GalaxyTypescript(); + + + async function run() { + const result = await galaxyTypescript.planets.updatePlanetJson({ + planetId: 1, + planet: { + name: "Mars", + description: "The red planet", + type: "terrestrial", + habitabilityIndex: 0.68, + physicalProperties: { + mass: 0.107, + radius: 0.532, + gravity: 0.378, + temperature: { + min: 130, + max: 308, + average: 210, + }, + }, + atmosphere: [ + { + compound: "CO2", + percentage: 95.3, + }, + ], + discoveredAt: new Date("1610-01-07T00:00:00Z"), + image: "https://cdn.scalar.com/photos/mars.jpg", + satellites: [ + { + name: "Phobos", + description: "Phobos is the larger and innermost of the two moons of Mars.", + diameter: 22.2, + type: "moon", + orbit: { + planet: { + id: 1, + name: "Mars", + description: "The red planet", + type: "terrestrial", + habitabilityIndex: 0.68, + physicalProperties: { + mass: 0.107, + radius: 0.532, + gravity: 0.378, + temperature: { + min: 130, + max: 308, + average: 210, + }, + }, + atmosphere: [ + { + compound: "CO2", + percentage: 95.3, + }, + ], + discoveredAt: new Date("1610-01-07T00:00:00Z"), + image: "https://cdn.scalar.com/photos/mars.jpg", + satellites: [ + { + id: 1, + name: "Phobos", + description: "Phobos is the larger and innermost of the two moons of Mars.", + diameter: 22.2, + type: "moon", + orbit: { + planet: { + id: 1, + name: "Mars", + description: "The red planet", + type: "terrestrial", + habitabilityIndex: 0.68, + physicalProperties: { + mass: 0.107, + radius: 0.532, + gravity: 0.378, + temperature: { + min: 130, + max: 308, + average: 210, + }, + }, + atmosphere: [ + { + compound: "CO2", + percentage: 95.3, + }, + ], + discoveredAt: new Date("1610-01-07T00:00:00Z"), + image: "https://cdn.scalar.com/photos/mars.jpg", + creator: { + id: 1, + name: "Marc", + }, + tags: [ + "solar-system", + "rocky", + "explored", + ], + lastUpdated: new Date("2024-01-15T14:30:00Z"), + successCallbackUrl: "https://example.com/webhook", + failureCallbackUrl: "https://example.com/webhook", + }, + orbitalPeriod: 0.319, + distance: 9376, + }, + }, + ], + creator: { + id: 1, + name: "Marc", + }, + tags: [ + "solar-system", + "rocky", + "explored", + ], + lastUpdated: new Date("2024-01-15T14:30:00Z"), + successCallbackUrl: "https://example.com/webhook", + failureCallbackUrl: "https://example.com/webhook", + }, + orbitalPeriod: 0.319, + distance: 9376, + }, + }, + ], + creator: { + name: "Marc", + }, + tags: [ + "solar-system", + "rocky", + "explored", + ], + successCallbackUrl: "https://example.com/webhook", + failureCallbackUrl: "https://example.com/webhook", + }, + }); + + console.log(result); + } + + + run(); delete: tags: - Planets summary: Delete a planet operationId: deletePlanet - description: - This endpoint was used to delete planets. Unfortunately, that caused - a lot of trouble for planets with life. So, this endpoint is now deprecated - and should not be used anymore. + description: This endpoint was used to delete planets. Unfortunately, that + caused a lot of trouble for planets with life. So, this endpoint is now + deprecated and should not be used anymore. x-scalar-stability: experimental parameters: - - $ref: '#/components/parameters/planetId' + - $ref: "#/components/parameters/planetId" responses: - '204': + "204": description: No Content - '404': - $ref: '#/components/responses/NotFound' - '/planets/{planetId}/image': + "404": + $ref: "#/components/responses/NotFound" + x-codeSamples: + - label: csharp + lang: csharp + source: |- + using Scalar.GalaxyCsharp; + + var sdk = new GalaxyCsharp(); + + var res = await sdk.Planets.DeletePlanetAsync(planetId: 1); + + // handle response + - label: typescript + lang: typescript + source: |- + import { GalaxyTypescript } from "@scalar/galaxy-typescript"; + + const galaxyTypescript = new GalaxyTypescript(); + + async function run() { + await galaxyTypescript.planets.deletePlanet({ + planetId: 1, + }); + + + } + + run(); + /planets/{planetId}/image: post: tags: - Planets @@ -301,7 +1008,7 @@ paths: description: Got a crazy good photo of a planet? Share it with the world! operationId: uploadImage parameters: - - $ref: '#/components/parameters/planetId' + - $ref: "#/components/parameters/planetId" requestBody: description: Image to upload content: @@ -314,18 +1021,59 @@ paths: format: binary description: The image file to upload examples: - - '@mars.jpg' - - '@jupiter.png' + - "@mars.jpg" + - "@jupiter.png" responses: - '200': - $ref: '#/components/responses/ImageUploaded' - '400': - $ref: '#/components/responses/BadRequest' - '403': - $ref: '#/components/responses/Forbidden' - '404': - $ref: '#/components/responses/NotFound' - '/celestial-bodies': + "200": + $ref: "#/components/responses/ImageUploaded" + "400": + $ref: "#/components/responses/BadRequest" + "403": + $ref: "#/components/responses/Forbidden" + "404": + $ref: "#/components/responses/NotFound" + x-codeSamples: + - label: csharp + lang: csharp + source: |- + using Scalar.GalaxyCsharp; + using Scalar.GalaxyCsharp.Models.Requests; + using System.IO; + + var sdk = new GalaxyCsharp(); + + var res = await sdk.Planets.UploadImageAsync( + planetId: 1, + requestBody: new UploadImageRequestBody() { + Image = new Image() { + FileName = "example.file", + Content = File.ReadAllBytes("example.file"), + }, + } + ); + + // handle response + - label: typescript + lang: typescript + source: |- + import { GalaxyTypescript } from "@scalar/galaxy-typescript"; + import { openAsBlob } from "node:fs"; + + const galaxyTypescript = new GalaxyTypescript(); + + async function run() { + const result = await galaxyTypescript.planets.uploadImage({ + planetId: 1, + requestBody: { + image: await openAsBlob("example.file"), + }, + }); + + console.log(result); + } + + run(); + /celestial-bodies: post: tags: - Celestial Bodies @@ -337,15 +1085,54 @@ paths: content: application/json: schema: - $ref: '#/components/schemas/CelestialBody' + $ref: "#/components/schemas/CelestialBody" responses: - '201': + "201": description: Celestial body created content: application/json: schema: - $ref: '#/components/schemas/CelestialBody' - '/user/signup': + $ref: "#/components/schemas/CelestialBody" + x-codeSamples: + - label: csharp + lang: csharp + source: |- + using Scalar.GalaxyCsharp; + using Scalar.GalaxyCsharp.Models.Components; + + var sdk = new GalaxyCsharp(); + + CelestialBodyInput req = CelestialBodyInput.CreateMoon( + new SatelliteInput1() { + Name = "Phobos", + Type = SatelliteType.Moon, + } + ); + + var res = await sdk.CelestialBodies.CreateCelestialBodyAsync(req); + + // handle response + - label: typescript + lang: typescript + source: >- + import { GalaxyTypescript } from "@scalar/galaxy-typescript"; + + + const galaxyTypescript = new GalaxyTypescript(); + + + async function run() { + const result = await galaxyTypescript.celestialBodies.createCelestialBody({ + name: "Phobos", + type: "moon", + }); + + console.log(result); + } + + + run(); + /user/signup: post: tags: - Authentication @@ -360,8 +1147,8 @@ paths: application/json: schema: allOf: - - $ref: '#/components/schemas/User' - - $ref: '#/components/schemas/Credentials' + - $ref: "#/components/schemas/User" + - $ref: "#/components/schemas/Credentials" examples: Marc: value: @@ -373,11 +1160,16 @@ paths: name: Cam email: cam@scalar.com password: scalar-is-cool + Hans: + value: + name: Hans + email: hans@scalar.com + password: 5c4l4r application/xml: schema: allOf: - - $ref: '#/components/schemas/User' - - $ref: '#/components/schemas/Credentials' + - $ref: "#/components/schemas/User" + - $ref: "#/components/schemas/Credentials" examples: Marc: value: @@ -389,79 +1181,161 @@ paths: name: Cam email: cam@scalar.com password: scalar-is-cool + Hans: + value: + name: Hans + email: hans@scalar.com + password: 5c4l4r responses: - '201': - description: Created + "201": + description: User account created successfully headers: X-Request-ID: - $ref: '#/components/headers/X-Request-ID' + $ref: "#/components/headers/X-Request-ID" Location: - $ref: '#/components/headers/Location' + $ref: "#/components/headers/Location" X-Processing-Time: - $ref: '#/components/headers/X-Processing-Time' + $ref: "#/components/headers/X-Processing-Time" content: application/json: schema: - $ref: '#/components/schemas/User' + $ref: "#/components/schemas/User" application/xml: schema: - $ref: '#/components/schemas/User' - '400': - $ref: '#/components/responses/BadRequest' - '401': - $ref: '#/components/responses/Unauthorized' - '403': - $ref: '#/components/responses/Forbidden' - '409': - $ref: '#/components/responses/Conflict' - '422': - $ref: '#/components/responses/UnprocessableEntity' - '/auth/token': + $ref: "#/components/schemas/User" + "400": + $ref: "#/components/responses/BadRequest" + "401": + $ref: "#/components/responses/Unauthorized" + "403": + $ref: "#/components/responses/Forbidden" + "409": + $ref: "#/components/responses/Conflict" + "422": + $ref: "#/components/responses/UnprocessableEntity" + x-codeSamples: + - label: csharp + lang: csharp + source: |- + using Scalar.GalaxyCsharp; + using Scalar.GalaxyCsharp.Models.Requests; + + var sdk = new GalaxyCsharp(); + + CreateUserJsonRequestBody req = new CreateUserJsonRequestBody() { + Name = "Marc", + Email = "marc@scalar.com", + Password = "i-love-scalar", + }; + + var res = await sdk.Authentication.CreateUserJsonAsync(req); + + // handle response + - label: typescript + lang: typescript + source: >- + import { GalaxyTypescript } from "@scalar/galaxy-typescript"; + + + const galaxyTypescript = new GalaxyTypescript(); + + + async function run() { + const result = await galaxyTypescript.authentication.createUserJson({ + name: "Marc", + email: "marc@scalar.com", + password: "i-love-scalar", + }); + + console.log(result); + } + + + run(); + /auth/token: post: tags: - Authentication summary: Get a token - description: Yeah, this is the boring security stuff. Just get your super secret token and move on. + description: Yeah, this is the boring security stuff. Just get your super secret + token and move on. operationId: getToken security: - {} requestBody: - description: Credentials to authenticate a user + description: Body for credentials to authenticate a user content: application/json: schema: - $ref: '#/components/schemas/Credentials' + $ref: "#/components/schemas/Credentials" application/xml: schema: - $ref: '#/components/schemas/Credentials' + $ref: "#/components/schemas/Credentials" responses: - '201': + "201": description: Token Created headers: X-Request-ID: - $ref: '#/components/headers/X-Request-ID' + $ref: "#/components/headers/X-Request-ID" X-RateLimit-Limit: - $ref: '#/components/headers/X-RateLimit-Limit' + $ref: "#/components/headers/X-RateLimit-Limit" X-RateLimit-Remaining: - $ref: '#/components/headers/X-RateLimit-Remaining' + $ref: "#/components/headers/X-RateLimit-Remaining" X-RateLimit-Reset: - $ref: '#/components/headers/X-RateLimit-Reset' + $ref: "#/components/headers/X-RateLimit-Reset" content: application/json: schema: - $ref: '#/components/schemas/Token' + $ref: "#/components/schemas/Token" application/xml: schema: - $ref: '#/components/schemas/Token' - '401': - $ref: '#/components/responses/Unauthorized' - '403': - $ref: '#/components/responses/Forbidden' - '400': - $ref: '#/components/responses/BadRequest' - '429': - $ref: '#/components/responses/TooManyRequests' - '/me': + $ref: "#/components/schemas/Token" + "400": + $ref: "#/components/responses/BadRequest" + "401": + $ref: "#/components/responses/Unauthorized" + "403": + $ref: "#/components/responses/Forbidden" + "429": + $ref: "#/components/responses/TooManyRequests" + x-codeSamples: + - label: csharp + lang: csharp + source: |- + using Scalar.GalaxyCsharp; + using Scalar.GalaxyCsharp.Models.Components; + + var sdk = new GalaxyCsharp(); + + Credentials req = new Credentials() { + Email = "marc@scalar.com", + Password = "i-love-scalar", + }; + + var res = await sdk.Authentication.GetTokenJsonAsync(req); + + // handle response + - label: typescript + lang: typescript + source: >- + import { GalaxyTypescript } from "@scalar/galaxy-typescript"; + + + const galaxyTypescript = new GalaxyTypescript(); + + + async function run() { + const result = await galaxyTypescript.authentication.getTokenJson({ + email: "marc@scalar.com", + password: "i-love-scalar", + }); + + console.log(result); + } + + + run(); + /me: get: tags: - Authentication @@ -476,28 +1350,53 @@ paths: - apiKeyHeader: [] - apiKeyQuery: [] responses: - '200': - description: OK + "200": + description: Authenticated user information retrieved successfully headers: X-Request-ID: - $ref: '#/components/headers/X-Request-ID' + $ref: "#/components/headers/X-Request-ID" ETag: - $ref: '#/components/headers/ETag' + $ref: "#/components/headers/ETag" Last-Modified: - $ref: '#/components/headers/Last-Modified' + $ref: "#/components/headers/Last-Modified" X-Cache-Control: - $ref: '#/components/headers/X-Cache-Control' + $ref: "#/components/headers/X-Cache-Control" content: application/json: schema: - $ref: '#/components/schemas/User' + $ref: "#/components/schemas/User" application/xml: schema: - $ref: '#/components/schemas/User' - '401': - $ref: '#/components/responses/Unauthorized' - '403': - $ref: '#/components/responses/Forbidden' + $ref: "#/components/schemas/User" + "401": + $ref: "#/components/responses/Unauthorized" + "403": + $ref: "#/components/responses/Forbidden" + x-codeSamples: + - label: csharp + lang: csharp + source: |- + using Scalar.GalaxyCsharp; + + var sdk = new GalaxyCsharp(); + + var res = await sdk.Authentication.GetMeAsync(); + + // handle response + - label: typescript + lang: typescript + source: |- + import { GalaxyTypescript } from "@scalar/galaxy-typescript"; + + const galaxyTypescript = new GalaxyTypescript(); + + async function run() { + const result = await galaxyTypescript.authentication.getMe(); + + console.log(result); + } + + run(); webhooks: newPlanet: post: @@ -508,14 +1407,10 @@ webhooks: content: application/json: schema: - $ref: '#/components/schemas/Planet' - application/xml: - schema: - $ref: '#/components/schemas/Planet' + $ref: "#/components/schemas/Planet" responses: - '200': - description: - Return a 200 status to indicate that the data was received + "200": + description: Return a 200 status to indicate that the data was received successfully components: securitySchemes: @@ -559,14 +1454,12 @@ components: read:account: read your account information write:planets: modify planets in your account read:planets: read your planets - # Legacy implicit: authorizationUrl: https://galaxy.scalar.com/oauth/authorize scopes: read:account: read your account information write:planets: modify planets in your account read:planets: read your planets - # Legacy password: tokenUrl: https://galaxy.scalar.com/oauth/token scopes: @@ -599,9 +1492,7 @@ components: default: 10 offset: name: offset - description: - The number of items to skip before starting to collect the result - set + description: The number of items to skip before starting to collect the result set in: query required: false schema: @@ -629,7 +1520,7 @@ components: schema: type: string format: uuid - example: '123e4567-e89b-12d3-a456-426614174000' + example: 123e4567-e89b-12d3-a456-426614174000 X-Pagination-Total: description: Total number of items available schema: @@ -649,7 +1540,7 @@ components: description: Cache control directives schema: type: string - example: 'max-age=3600, public' + example: max-age=3600, public ETag: description: Entity tag for caching schema: @@ -660,13 +1551,13 @@ components: schema: type: string format: date-time - example: '2023-12-01T12:00:00Z' + example: 2023-12-01T12:00:00Z Location: description: The URL of the newly created resource schema: type: string format: uri - example: 'https://galaxy.scalar.com/planets/123' + example: https://galaxy.scalar.com/planets/123 X-Processing-Time: description: The time taken to process the request in milliseconds schema: @@ -677,84 +1568,84 @@ components: description: Image uploaded headers: X-Request-ID: - $ref: '#/components/headers/X-Request-ID' + $ref: "#/components/headers/X-Request-ID" X-Cache-Control: - $ref: '#/components/headers/X-Cache-Control' + $ref: "#/components/headers/X-Cache-Control" content: application/json: schema: - $ref: '#/components/schemas/ImageUploadedMessage' + $ref: "#/components/schemas/ImageUploadedMessage" application/xml: schema: - $ref: '#/components/schemas/ImageUploadedMessage' + $ref: "#/components/schemas/ImageUploadedMessage" BadRequest: description: Bad Request headers: X-Request-ID: - $ref: '#/components/headers/X-Request-ID' + $ref: "#/components/headers/X-Request-ID" content: application/json: schema: - $ref: '#/components/schemas/BadRequestError' + $ref: "#/components/schemas/BadRequestError" application/xml: schema: - $ref: '#/components/schemas/BadRequestError' + $ref: "#/components/schemas/BadRequestError" Forbidden: description: Forbidden content: application/json: schema: - $ref: '#/components/schemas/ForbiddenError' + $ref: "#/components/schemas/ForbiddenError" application/xml: schema: - $ref: '#/components/schemas/ForbiddenError' + $ref: "#/components/schemas/ForbiddenError" NotFound: description: Not Found content: application/json: schema: - $ref: '#/components/schemas/NotFoundError' + $ref: "#/components/schemas/NotFoundError" application/xml: schema: - $ref: '#/components/schemas/NotFoundError' + $ref: "#/components/schemas/NotFoundError" Unauthorized: description: Unauthorized content: application/json: schema: - $ref: '#/components/schemas/UnauthorizedError' + $ref: "#/components/schemas/UnauthorizedError" application/xml: schema: - $ref: '#/components/schemas/UnauthorizedError' + $ref: "#/components/schemas/UnauthorizedError" Conflict: description: Conflict content: application/json: schema: - $ref: '#/components/schemas/Conflict' + $ref: "#/components/schemas/Conflict" application/xml: schema: - $ref: '#/components/schemas/Conflict' + $ref: "#/components/schemas/Conflict" UnprocessableEntity: description: Unprocessable Entity content: application/json: schema: - $ref: '#/components/schemas/UnprocessableEntity' + $ref: "#/components/schemas/UnprocessableEntity" application/xml: schema: - $ref: '#/components/schemas/UnprocessableEntity' + $ref: "#/components/schemas/UnprocessableEntity" TooManyRequests: description: Too Many Requests headers: X-Request-ID: - $ref: '#/components/headers/X-Request-ID' + $ref: "#/components/headers/X-Request-ID" X-RateLimit-Limit: - $ref: '#/components/headers/X-RateLimit-Limit' + $ref: "#/components/headers/X-RateLimit-Limit" X-RateLimit-Remaining: - $ref: '#/components/headers/X-RateLimit-Remaining' + $ref: "#/components/headers/X-RateLimit-Remaining" X-RateLimit-Reset: - $ref: '#/components/headers/X-RateLimit-Reset' + $ref: "#/components/headers/X-RateLimit-Reset" Retry-After: description: The number of seconds to wait before retrying schema: @@ -763,10 +1654,10 @@ components: content: application/json: schema: - $ref: '#/components/schemas/TooManyRequestsError' + $ref: "#/components/schemas/TooManyRequestsError" application/xml: schema: - $ref: '#/components/schemas/TooManyRequestsError' + $ref: "#/components/schemas/TooManyRequestsError" schemas: User: description: A user @@ -784,6 +1675,8 @@ components: type: string examples: - Marc + - Cam + - Hans Credentials: description: Credentials to authenticate a user type: object @@ -796,13 +1689,15 @@ components: format: email examples: - marc@scalar.com + - cam@scalar.com + - hans@scalar.com password: type: string writeOnly: true examples: - i-love-scalar - - i-love-OSS - - i-love-code + - i-love-oss + - qwerty123 Token: description: A token to authenticate a user type: object @@ -813,13 +1708,19 @@ components: - eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c CelestialBody: oneOf: - - $ref: '#/components/schemas/Planet' - - $ref: '#/components/schemas/Satellite' + - $ref: "#/components/schemas/Planet" + - $ref: "#/components/schemas/Satellite" discriminator: propertyName: type mapping: - planet: '#/components/schemas/Planet' - satellite: '#/components/schemas/Satellite' + terrestrial: "#/components/schemas/Planet" + gas_giant: "#/components/schemas/Planet" + ice_giant: "#/components/schemas/Planet" + dwarf: "#/components/schemas/Planet" + super_earth: "#/components/schemas/Planet" + moon: "#/components/schemas/Satellite" + asteroid: "#/components/schemas/Satellite" + comet: "#/components/schemas/Satellite" description: A celestial body which can be either a planet or a satellite Planet: description: A planet in the Scalar Galaxy @@ -847,7 +1748,7 @@ components: description: type: - string - - 'null' + - "null" examples: - The red planet - A gas giant with a great red spot @@ -867,8 +1768,10 @@ components: - SuperEarth x-enum-descriptions: terrestrial: Rocky planets with solid surfaces, like Earth and Mars - gas_giant: Large planets composed mainly of hydrogen and helium, like Jupiter and Saturn - ice_giant: Planets composed of water, ammonia, and methane ices, like Uranus and Neptune + gas_giant: Large planets composed mainly of hydrogen and helium, like Jupiter + and Saturn + ice_giant: Planets composed of water, ammonia, and methane ices, like Uranus and + Neptune dwarf: Small planetary bodies that don't meet full planet criteria, like Pluto super_earth: Rocky planets larger than Earth but smaller than gas giants examples: @@ -960,30 +1863,33 @@ components: type: string format: date-time examples: - - '1610-01-07T00:00:00Z' + - 1610-01-07T00:00:00Z image: - type: string - nullable: true + type: + - string + - "null" examples: - https://cdn.scalar.com/photos/mars.jpg satellites: type: array items: - $ref: '#/components/schemas/Satellite' + $ref: "#/components/schemas/Satellite" creator: - $ref: '#/components/schemas/User' + $ref: "#/components/schemas/User" tags: type: array items: type: string examples: - - ['solar-system', 'rocky', 'explored'] + - - solar-system + - rocky + - explored lastUpdated: type: string format: date-time readOnly: true examples: - - '2024-01-15T14:30:00Z' + - 2024-01-15T14:30:00Z successCallbackUrl: type: string format: uri @@ -1015,7 +1921,7 @@ components: description: type: - string - - 'null' + - "null" examples: - Phobos is the larger and innermost of the two moons of Mars. diameter: @@ -1037,18 +1943,15 @@ components: x-enum-descriptions: moon: Natural satellites that orbit planets asteroid: Rocky objects that orbit the sun, typically found in the asteroid belt - comet: Icy bodies that release gas when approaching the sun, creating visible tails + comet: Icy bodies that release gas when approaching the sun, creating visible + tails examples: - moon orbit: type: object properties: - planetId: - type: integer - format: int64 - description: The ID of the planet this satellite orbits - examples: - - 1 + planet: + $ref: "#/components/schemas/Planet" orbitalPeriod: type: number format: float @@ -1086,9 +1989,9 @@ components: next: type: - string - - 'null' + - "null" examples: - - '/planets?limit=10&offset=10' + - /planets?limit=10&offset=10 ImageUploadedMessage: x-scalar-ignore: true description: Message about an image upload @@ -1108,7 +2011,7 @@ components: format: date-time description: Timestamp when the image was uploaded examples: - - '2024-01-15T14:30:00Z' + - 2024-01-15T14:30:00Z fileSize: type: integer description: Size of the uploaded image in bytes @@ -1144,7 +2047,8 @@ components: - The request was invalid. ForbiddenError: x-scalar-ignore: true - description: RFC 7807 (https://datatracker.ietf.org/doc/html/rfc7807) + description: Error response for forbidden access (RFC 7807). Returned when the + user does not have permission to access the requested resource. type: object properties: type: @@ -1166,7 +2070,8 @@ components: - You are not authorized to access this resource. NotFoundError: x-scalar-ignore: true - description: RFC 7807 (https://datatracker.ietf.org/doc/html/rfc7807) + description: Error response for resource not found (RFC 7807). Returned when the + requested resource does not exist. type: object properties: type: @@ -1188,7 +2093,8 @@ components: - The resource you are trying to access does not exist. UnauthorizedError: x-scalar-ignore: true - description: RFC 7807 (https://datatracker.ietf.org/doc/html/rfc7807) + description: Error response for unauthorized access (RFC 7807). Returned when + authentication is required or has failed. type: object properties: type: @@ -1210,7 +2116,8 @@ components: - You are not authorized to access this resource. Conflict: x-scalar-ignore: true - description: RFC 7807 (https://datatracker.ietf.org/doc/html/rfc7807) + description: Error response for resource conflicts (RFC 7807). Returned when the + request conflicts with the current state of the resource. type: object properties: type: @@ -1232,7 +2139,8 @@ components: - The resource you are trying to access is in conflict. UnprocessableEntity: x-scalar-ignore: true - description: RFC 7807 (https://datatracker.ietf.org/doc/html/rfc7807) + description: Error response for unprocessable entity (RFC 7807). Returned when + the request is well-formed but contains semantic errors. type: object properties: type: @@ -1254,7 +2162,8 @@ components: - The request was invalid. TooManyRequestsError: x-scalar-ignore: true - description: RFC 7807 (https://datatracker.ietf.org/doc/html/rfc7807) + description: Error response for rate limiting (RFC 7807). Returned when the + client has exceeded the rate limit for requests. type: object properties: type: diff --git a/docs/content/api-references.md b/docs/content/api-references.md new file mode 100644 index 0000000..a6c4163 --- /dev/null +++ b/docs/content/api-references.md @@ -0,0 +1,95 @@ +# API References + +Scalar supports three ways to add OpenAPI documents to your documentation: using a local file, the [Scalar Registry](https://scalar.com/products/registry/getting-started) or a remote URL. + +## Using a Local File + +Reference an OpenAPI file stored in your GitHub repository by specifying a relative path from your configuration root: + +```json +{ + "$schema": "https://cdn.scalar.com/schema/scalar-config-next.json", + "scalar": "2.0.0", + "navigation": { + "routes": { + "/api": { + "type": "openapi", + "title": "My API", + "filepath": "docs/api-reference/openapi.yaml", + "icon": "phosphor/regular/plug" + } + } + } +} +``` + +## Using the Scalar Registry + +Upload your OpenAPI document to the [Scalar Registry](https://scalar.com/products/registry/getting-started): + +```bash +scalar auth login +scalar registry publish ./openapi.yaml --namespace my-organization --slug my-api +``` + +And reference it using a namespace, slug, and version (optional): + +```json +{ + "$schema": "https://cdn.scalar.com/schema/scalar-config-next.json", + "scalar": "2.0.0", + "navigation": { + "routes": { + "/api": { + "type": "openapi", + "title": "My API", + "namespace": "my-organization", + "slug": "my-api", + // "version": "1.0.0", + "icon": "phosphor/regular/plug" + } + } + } +} +``` + +## Using a URL + +Fetch an OpenAPI document from a remote URL. The document is fetched on each page load, keeping your documentation in sync with your live API: + +```json +{ + "$schema": "https://cdn.scalar.com/schema/scalar-config-next.json", + "scalar": "2.0.0", + "navigation": { + "routes": { + "/api": { + "type": "openapi", + "title": "My API", + "url": "https://api.example.com/openapi.json", + "icon": "phosphor/regular/plug" + } + } + } +} +``` + +## Configuration + +All OpenAPI entries support the following options: + +| Option | Type | Description | +| ------------- | ------------------------------------ | ----------------------------------------------------------- | +| `type` | `"openapi"` | Required: Identifies this as an OpenAPI document. | +| `title` | `string` | Title shown in navigation links. | +| `description` | `string` | Description for the API reference. | +| `icon` | `string` | Icon to display in the sidebar. | +| `mode` | `"nested"` \| `"flat"` \| `"folder"` | How to display the API in the sidebar. Default: `"folder"`. | +| `config` | `object` | Scalar API Reference configuration | + +### Display Modes + +- `folder` (default): Shows a single level of links with a folder icon +- `flat` Shows a single level of links with a section title +- `nested` Shows a sub-sidebar with breadcrumbs for deep navigation + diff --git a/docs/content/development.md b/docs/content/development.md new file mode 100644 index 0000000..8ba4613 --- /dev/null +++ b/docs/content/development.md @@ -0,0 +1,24 @@ +# Development + +## Local Preview + +Run `@scalar/cli project preview` to start a local development server with live reload. + +## Port + +The default port is `7970`. Override with `--port`: + +```sh +npx @scalar/cli project preview --port 3000 +``` + +If the port is in use, the CLI selects another automatically. + +## Configuration + +The CLI looks for `scalar.config.json` in the current directory by default. To use a different config: + +```sh +npx @scalar/cli project preview my-scalar-config.json +npx @scalar/cli project preview ../some-other-directory/scalar.config.json +``` diff --git a/docs/content/quickstart.md b/docs/content/quickstart.md new file mode 100644 index 0000000..bc80996 --- /dev/null +++ b/docs/content/quickstart.md @@ -0,0 +1,57 @@ +# Quickstart + +This is the Scalar Docs Starter Kit — a ready-to-use template for building beautiful documentation. Fork it, clone it, and make it your own. Everything here is meant to be modified, extended, or replaced to fit your project. + +## 1. Preview Your Docs + +Run a local development server to see your changes in real-time: + +```bash +npx @scalar/cli project preview +``` + +This starts a live preview at `http://localhost:7971` where every edit you make is instantly visible. + +Read more about [Development](development.md). + +## 2. Include OpenAPI Documents + +Drop your OpenAPI files into `docs/api-reference/`, and add them to `@scalar.config.json` to have them automatically become interactive API references. + +The starter kit includes an example OpenAPI document to show you how it works. + +Read more about [API References](api-references.md) + +## 3. Customize Everything + +Make it yours with themes, custom CSS, and MDX. Configure your documentation structure, navigation, and styling through `scalar.config.json`. + +## 4. Publish Your Docs + +First, authenticate with your Scalar account: + +```bash +npx @scalar/cli auth login +``` + +Then publish your documentation: + +```bash +npx @scalar/cli project publish +``` + +Your site will be available at `.apidocumentation.com`. + +## Stuck? + +Check whether your `scalar.config.json` is valid: + +```bash +npx @scalar/cli project check-config +``` + +We're here to help: + +- [Email support@scalar.com](mailto:support@scalar.com) +- [Chat with us on Discord](https://discord.gg/scalar) +- [Schedule a call](https://scalar.cal.com/scalar/chat-with-scalar) diff --git a/docs/guides/quick-start/details/api-client.md b/docs/guides/quick-start/details/api-client.md deleted file mode 100644 index d53db52..0000000 --- a/docs/guides/quick-start/details/api-client.md +++ /dev/null @@ -1,39 +0,0 @@ -# API Client - -Make use of an auto-generated, full featured & [open-source](https://github.com/scalar/scalar) API client - built by us + our community - by including **OpenAPI** documents or references within the `references` section of your project's `scalar.config.json5` file! - -## Features - - - -:::scalar-card{title="API Framework Integration"} -Link to your server frameworks and keep Scalar's API Client in sync -(coming soon) -::: - -:::scalar-card{title="Offline First"} -We built this product for ourselves, offline first & always will be. If your team needs collaboration it's opt-in -::: - -:::scalar-card{title="Collaboration"} -Your team needs to collaborate on testing APIs? We got you covered with our sync that's on our paid plan -::: - - - - -:::scalar-card{title="All Platforms"} -Web? MacOS? Linux? Windows? We release on all platforms so you can work seamlessy with your preferred dev setup -::: - -:::scalar-card{title="OpenAPI Support"} -We keep the OpenAPI spec alive, getting all the downstream benefits of building with Scalar from docs to sdks -::: - -:::scalar-card{title="No Vendor Lock In"} -Don't stress your engineering team out, our API Client is built all based on the OpenAPI Specification -::: - - - -::scalar-page-link{filepath="docs/guides/quick-start/introduction.md" title="Take me back" description="Return to the Overview."} diff --git a/docs/guides/quick-start/details/development.md b/docs/guides/quick-start/details/development.md deleted file mode 100644 index 00b8417..0000000 --- a/docs/guides/quick-start/details/development.md +++ /dev/null @@ -1,34 +0,0 @@ -# Development -Live preview your changes while your work on your docs site! - -Run `@scalar/cli project preview` and a local preview of your site will be opened. - -## Ports -By default the CLI uses `7970`. You can also pass a desired port via the `--port ` flag. - -:::scalar-callout{type="info"} -If the port is in use, the cli will select another port automatically. -::: - -## Passing the Config -The CLI will automatically look for your `scalar.config.json5` file in the current directory. - -You can use a different name, or a config from a different directory, by passing it directly to the -preview command. - -```sh -npx @scalar/cli project preview my-scalar-config.json5 -npx @scalar/cli project preview ../other-dir/scalar.config.json5 -``` - -## Automatic Opening -To prevent the CLI from automatically opening a new tab in your browser at the current port, you can pass the `--no-open` -flag. - -:::scalar-callout{type="warning"} -The preview works best if only open in a single tab at a time. -::: - -## Debugging - -You can turn on the debugging logs with `--log-level debug` diff --git a/docs/guides/quick-start/details/project-settings.md b/docs/guides/quick-start/details/project-settings.md deleted file mode 100644 index ad081ce..0000000 --- a/docs/guides/quick-start/details/project-settings.md +++ /dev/null @@ -1,94 +0,0 @@ -# Project Settings - -Your Scalar project is highly customizable by updating your `scalar.config.json5` file. - -:::scalar-callout{type="info"} -Check the fully detailed [JSON Schema](https://cdn.scalar.com/schema/scalar-config.json) for all possible options. -::: - -## Properties - -### subdomain -`string` _required_ - -The subdomain for your Scalar docs site. - -:::scalar-detail{title="Example"} -``` -"subdomain": "starter-kit.apidocumentation.com" -``` -::: - -### references -`Array` _optional_ - -A list of API references. - -These will be used to auto-generate API clients on your site. - -:::scalar-detail{title="Example"} -``` -"references": [ - { - "name": "Planets", - "path": "./docs/api-reference/open-api-spec.yaml" - } -], -``` -::: - -### guides -`Array` _optional_ - -An array of guide entries. Each entry will become its own tab, with a sidebar navigation of the entries -provided in its `sidebar` array. - -::::scalar-detail{title="Example"} -This yields two guides, `First Guide` and `Second Guide`. - -The `First Guide` will have two sidebar entries (a folder and a file), and `Second Guide` will have only one. -``` - "guides": [ - { - "name": "First Guide", - "sidebar": [ - { - "name": "Folder Example", - "type": "folder", - "children": [ - { "path": "path/to/file-1.md", "type": "page", name: "Folder: File One" }, - ] - }, - { "path": "path/to/file-2.md", "type": "page", name: "File Two" }, - ] - }, - { - "name": "Second Guide", - "sidebar": [ - { "path": "path/to/file-3.md", "type": "page", name: "File Three" }, - ] - }, - ], -``` - -:::scalar-callout{type=warning} -The guides are recursively defined: a sidebar entry may have it's own `sidebar` with further sidebar entries. -::: -:::: - -### siteConfig -`object` _optional_ - -An object storing meta-data for your site, including theme, logos and more. - -:::scalar-detail{title="Example"} -``` -"siteConfig": { - "theme": "purple", - "logo": { - "darkMode": "https://scalar.com/logo-light.svg", - "lightMode": "https://scalar.com/logo-dark.svg" - }, -} -``` -::: diff --git a/docs/guides/quick-start/details/quickstart.md b/docs/guides/quick-start/details/quickstart.md deleted file mode 100644 index 2404e3d..0000000 --- a/docs/guides/quick-start/details/quickstart.md +++ /dev/null @@ -1,96 +0,0 @@ -# Quickstart -Get your documentation site up in a flash. - -## Local Setup -You can run the Scalar CLI by either installing it, or executing it via `npx`. - - -```sh -npm -g install @scalar/cli -``` - - -If you prefer not to install the cli, just prefix all commands with `npx @scalar/cli` instead of `scalar`. - - - -## Start a Project -No `scalar config` file? No problem! - - - -Fill this in what your prefered subdomain. -```sh -cat >> scalar.config.json5 <<'EOF' -{ - "subdomain": "your-prefered-subdomain.apidocumentation.com", - "references": [], - "guides": [] -} -EOF -``` - - -```sh -npx @scalar/cli project preview -``` - - - -Your (currently empty) documentation site should now be up and running! - -## Publish - - -Add an entry to your `guides` section of the `scalar.config.json5`. -This can be as simple as: - -```json -{ - "name": "Guide Name", - "sidebar":[ - { - name: "Guide entry name", - type: "page", - path: "relative/path/from/scalar-config/to/file.md" - }, - ] -}, -``` - - - -Before we can publish we need to authorize! -:::scalar-callout{type=warning} -This command will redirect you to your browser to log in -::: -```sh -npx @scalar/cli auth login -``` -After logging in we can create a project. You'll need to pass a `name` and `slug`. - -```sh -npx @scalar/cli project create --name your-preferred-project-name \ ---slug costasiella-kuroshimae -``` - - - -```sh -npx @scalar/cli project publish -``` - - - - -That's it! You can now visit your published site at `.apidocumentation.com` - -:::scalar-callout{type="info"} -**Our phone lines are open, 24/7.** - -:scalar-icon{src="discord-logo"} Chat with us on [Discord](https://discord.gg/scalar) - -:scalar-icon{src="phone"} Set up a [call](https://cal.com/scalar/30min) - -:scalar-icon{src="star"} Star us on [GitHub](https://github.com/scalar/scalar) -::: diff --git a/docs/guides/quick-start/details/scalar-cli.md b/docs/guides/quick-start/details/scalar-cli.md deleted file mode 100644 index f19bbc2..0000000 --- a/docs/guides/quick-start/details/scalar-cli.md +++ /dev/null @@ -1,9 +0,0 @@ -# CLI: install - -The [cli](https://www.npmjs.com/package/@scalar/cli) can be installed with: - -```sh -npm i @scalar/cli -``` - -Read [more about the CLI](https://guides.scalar.com/scalar/scalar-cli/getting-started) diff --git a/docs/guides/quick-start/details/syntax.md b/docs/guides/quick-start/details/syntax.md deleted file mode 100644 index a0189e0..0000000 --- a/docs/guides/quick-start/details/syntax.md +++ /dev/null @@ -1,92 +0,0 @@ -# Extended Markdown Syntax - -Scalar supports Github Flavored Markdown (GFM), as well as custom extensions written in either _directive_ or _custom-html_ syntax. - -For the most update-to-date documentation on our extended syntax see the `Scalar Docs` guides at `guides.scalar.com` - -::scalar-button{title="View Documentation" href="https://guides.scalar.com/scalar/scalar-docs/components"} - -## Directive Syntax -The directive syntax uses colons to denote a feature from plaintext, for example `:scalar-icon{src="acorn"}` - -A directive receives properties through `{prop="value here" other="more values"}` structures. This is optional. - -:::scalar-callout -There are 2 versions: `inline`, and `block`. -::: - -### Inline -The inline syntax allows you to place the directive anywhere within the current line. -When using this syntax you only need a single `:` before the name, and _you should not have a closing `:`. -If you need to pass content it must go after the name, before the parameters, in square brackets. - -:::scalar-detail{title=Example} -``` -_with optional content_ -:scalar-button[Optional Content]{title="View Documentation" href="https://docs.scalar.com"} - -_with only parameters_ -:scalar-button{title="View Documentation" href="https://docs.scalar.com"} -``` -::: - -### Block -The `block` syntax must: -- start with 3 or more `:` -- end with the same amount of `:` -- begin at the start of a line -- end at the start of another line - -Content written between the starting-line and ending-line will be parsed and inserted -into the directive (_the detail dropdowns on this page are done with `block directive` syntax_). - -::::scalar-detail{title=Example} -```` -_a valid block directive_ -:::scalar-detail{title=Example} -This would be inside the detail itself -::: - -_an invalid block directive, does not end with ::: at the start of a line -:::scalar-detail{title=Example} -This would be inside the detail itself -this conent makes the block invalid::: -```` -:::: - -## Custom Html Syntax -The custom html syntax look like html tags, prepended with `scalar-`. All tags must be closed with a matching tag, -even if there is no content between them. - - -``` - - - - - -Here is some additional content. - -``` - - - -## Available Features -In addition to all standard markdown features and GFM features, Scalar also supports: - - diff --git a/docs/guides/quick-start/introduction.md b/docs/guides/quick-start/introduction.md deleted file mode 100644 index 51785a8..0000000 --- a/docs/guides/quick-start/introduction.md +++ /dev/null @@ -1,33 +0,0 @@ -# Introduction - -Welcome to Scalar! - -## Getting Ready -::scalar-page-link{filepath="docs/guides/quick-start/details/quickstart.md" title="Start here" description="Follow the quickstart guide."} - -## Your Docs, Your Way -Three steps to beautiful docs. - - - -:::scalar-step{title="Iterate locally" interactivity="none"} -:scalar-icon{src="pencil-simple"} Edit your docs and watch them update in real time. -::scalar-page-link{filepath="docs/guides/quick-start/details/development.md" title="Live Previewing" description="Use the cli for local development."} -::: - -:::scalar-step{title="Add API refs" interactivity="none"} -:scalar-icon{src="files"} Include OpenAPI references. -::scalar-page-link{filepath="docs/guides/quick-start/details/api-client.md" title="API Client" description="Auto-generate an API client from your OpenAPI spec."} -::: - -:::scalar-step{title="Make it yours" interactivity="none"} -:scalar-icon{src="dna"} Write interactive docs and set themes with ease. -::scalar-page-link{filepath="docs/guides/quick-start/details/syntax.md" title="Extended Markdown syntax" description="See all the ways you can write your docs with our custom syntax."} -::: - - - -## Diving In -power of directives -code samples -images diff --git a/scalar.config.json b/scalar.config.json index f51660b..ffbcf7c 100644 --- a/scalar.config.json +++ b/scalar.config.json @@ -1,52 +1,68 @@ { - "$schema": "https://cdn.scalar.com/schema/scalar-config.json", + "$schema": "https://cdn.scalar.com/schema/scalar-config-next.json", + "scalar": "2.0.0", + "info": { + "title": "Scalar Starter Kit", + "description": "Get Started with the Scalar Docs" + }, "siteConfig": { - "theme": "purple", "logo": { - "darkMode": "https://scalar.com/logo-light.svg", - "lightMode": "https://scalar.com/logo-dark.svg" + "darkMode": "https://cdn.scalar.com/marketing/landing/logo-dark.svg", + "lightMode": "https://cdn.scalar.com/marketing/landing/logo-light.svg" } }, - "guides": [ - { - "name": "Quick Start", - "sidebar": [ - { - "name": "Getting Started with Scalar", - "type": "folder", - "icon": "rocket", - "children": [ - { "path": "docs/guides/quick-start/introduction.md", "type": "page", "name": "Overview" }, - { "path": "docs/guides/quick-start/details/quickstart.md", "type": "page", "name": "Quickstart" }, - { "path": "docs/guides/quick-start/details/development.md", "type": "page", "name": "Development" } - ] - }, - { - "name": "Customizing Your Setup", - "type": "folder", - "icon": "gear", - "children": [ - { "path": "docs/guides/quick-start/details/project-settings.md", "type": "page", "name": "Project Settings" }, - { "path": "docs/guides/quick-start/details/api-client.md", "type": "page", "name": "API Client" } - ] - }, - { - "name": "Appendix", - "type": "folder", - "icon": "notebook", - "defaultOpen": false, - "children": [ - { "path": "docs/guides/quick-start/details/scalar-cli.md", "type": "page", "name": "Scalar CLI" }, - { "path": "docs/guides/quick-start/details/syntax.md", "type": "page", "name": "Syntax" } - ] + "navigation": { + "routes": { + "/": { + "type": "group", + "title": "Scalar Starter Kit", + "children": { + "/": { + "type": "page", + "filepath": "docs/content/quickstart.md", + "title": "Quickstart", + "icon": "phosphor/regular/fast-forward" + }, + "/usage": { + "type": "group", + "title": "Usage", + "mode": "flat", + "children": { + "/development": { + "type": "page", + "filepath": "docs/content/development.md", + "title": "Development", + "icon": "phosphor/regular/code" + }, + "/api-references": { + "type": "page", + "filepath": "docs/content/api-references.md", + "title": "API References", + "icon": "phosphor/regular/notebook" + }, + "/documentation": { + "title": "Full Documentation", + "icon": "phosphor/regular/book", + "url": "https://scalar.com/products/docs/getting-started", + "type": "link" + } + } + }, + "/examples": { + "type": "group", + "title": "Examples", + "mode": "flat", + "children": { + "/api": { + "type": "openapi", + "filepath": "docs/api-reference/openapi.yaml", + "title": "Example API", + "icon": "phosphor/regular/plug" + } + } + } } - ] - } - ], - "references": [ - { - "name": "API Reference", - "path": "./docs/api-reference/openapi.yaml" + } } - ] + } }