feat(platzi): add Platzi docset and Scalar API playground with full n…

docs/devdocify/reference/index.md

@@ -30,13 +30,14 @@ Use reference pages when you need exact facts, supported options, and stable tec
   <p><code>/docs</code> first-party technical product docs (Diataxis)</p>
   <p><code>/tfl</code> demo TfL product docs</p>
   <p><code>/petstore</code> demo Petstore product docs</p>
-  <p><code>/tfl/api-playground</code> and <code>/petstore/api-playground</code> interactive demo routes</p>
+  <p><code>/platzi</code> demo Platzi Fake Store docs</p>
+  <p><code>/tfl/api-playground</code>, <code>/petstore/api-playground</code>, and <code>/platzi/api-playground</code> interactive demo routes</p>
 </div>
 
 ## Configuration entry points
 
 - Site config: `docusaurus.config.ts`
-- Sidebars: `sidebarsDevDocify.ts`, `sidebarsTfl.ts`, `sidebarsPetstore.ts`
+- Sidebars: `sidebarsDevDocify.ts`, `sidebarsTfl.ts`, `sidebarsPetstore.ts`, `sidebarsPlatzi.ts`
 - Navigation contract loader: `navigation-contract.ts`
 - Navigation definitions: `docs/*/navigation.json`
 - Workflows: `.github/workflows/ci.yml`, `.github/workflows/deploy.yml`, `.github/workflows/preview.yml`

docs/devdocify/reference/navigation-contract.md

@@ -11,6 +11,7 @@ Navigation for each docset is defined in one file:
 - `docs/devdocify/navigation.json`
 - `docs/tfl/navigation.json`
 - `docs/petstore/navigation.json`
+- `docs/platzi/navigation.json`
 
 These files are loaded and validated by `navigation-contract.ts` and then consumed by each sidebar entrypoint.
 

docs/devdocify/tutorials/index.md

@@ -32,5 +32,7 @@ After completing the quick start, explore the demo docsets to see multi-docset n
 
 - [TfL getting started](/tfl/getting-started)
 - [Petstore getting started](/petstore/getting-started)
+- [Platzi getting started](/platzi/getting-started)
 - [TfL API playground](/tfl/api-playground)
 - [Petstore API playground](/petstore/api-playground)
+- [Platzi API playground](/platzi/api-playground)

docs/platzi/getting-started/authentication.md

@@ -0,0 +1,36 @@
+---
+title: Authentication
+sidebar_position: 3
+description: JWT login, refresh, and profile retrieval for Platzi demo endpoints.
+---
+
+# Authentication
+
+The Platzi demo API uses JWT for protected endpoints.
+
+## Login
+
+```bash
+curl -X POST "https://api.escuelajs.co/api/v1/auth/login" \
+  -H "content-type: application/json" \
+  -d '{"email":"john@mail.com","password":"changeme"}'
+```
+
+Response includes `access_token` and `refresh_token`.
+
+## Profile (requires bearer token)
+
+```bash
+curl "https://api.escuelajs.co/api/v1/auth/profile" \
+  -H "authorization: Bearer <access_token>"
+```
+
+## Refresh token
+
+```bash
+curl -X POST "https://api.escuelajs.co/api/v1/auth/refresh-token" \
+  -H "content-type: application/json" \
+  -d '{"refreshToken":"<refresh_token>"}'
+```
+
+Use the [API playground](/platzi/api-playground) to run these flows interactively.

docs/platzi/getting-started/error-handling.md

@@ -0,0 +1,30 @@
+---
+title: Error handling
+sidebar_position: 4
+description: Common response codes for Platzi playground operations.
+---
+
+# Error handling
+
+Common response patterns in this demo API:
+
+- `200`: Request succeeded.
+- `400`: Bad request (missing/invalid payload or parameters).
+- `401`: Missing or invalid bearer token for protected endpoints.
+- `404`: Resource not found.
+- `429`: Rate limiting may be applied.
+- `5xx`: Upstream server error.
+
+## Expected example: profile without token
+
+```bash
+curl -i "https://api.escuelajs.co/api/v1/auth/profile"
+```
+
+Expected status: `401`.
+
+## Debug checklist
+
+- Confirm request path and method match the OpenAPI operation.
+- Confirm `content-type: application/json` for POST payloads.
+- Confirm bearer token is present for `/auth/profile`.

docs/platzi/getting-started/index.md

@@ -0,0 +1,33 @@
+---
+slug: /getting-started
+title: Platzi Fake Store API
+sidebar_position: 1
+description: Start here for the Platzi demo docset and curated Scalar playground operations.
+---
+
+# Platzi Fake Store API
+
+This docset demonstrates the public [Platzi Fake Store API](https://fakeapi.platzi.com/) in the same style as the TfL and Petstore demos.
+
+## Base URL
+
+```text
+https://api.escuelajs.co/api/v1
+```
+
+## What this playground includes
+
+- Product listing with pagination
+- Categories listing
+- Users listing and email availability checks
+- JWT login and profile retrieval
+- Locations endpoint for map-style demos
+
+Use the [API playground](/platzi/api-playground) for interactive requests in-browser.
+
+## Start with these pages
+
+- [Quickstart](/platzi/getting-started/quickstart)
+- [Authentication](/platzi/getting-started/authentication)
+- [Error handling](/platzi/getting-started/error-handling)
+- [Playground guide](/platzi/getting-started/playground)

docs/platzi/getting-started/playground.md

@@ -0,0 +1,32 @@
+---
+title: Playground guide
+sidebar_position: 5
+description: Scope and intent of the Platzi Scalar playground.
+---
+
+# Playground guide
+
+The Platzi playground is a curated subset of the live API for predictable demos.
+
+## Included operations
+
+- `GET /products`
+- `GET /categories`
+- `GET /users`
+- `POST /users/is-available`
+- `POST /auth/login`
+- `POST /auth/refresh-token`
+- `GET /auth/profile`
+- `GET /locations`
+
+## Scope notes
+
+- Data is shared and mutable on the public demo backend.
+- IDs and content can change between requests.
+- Use list/search endpoints for the most stable demos.
+
+## Links
+
+- Playground: [/platzi/api-playground](/platzi/api-playground)
+- Download spec: [/openapi/platzi-playground.json](/openapi/platzi-playground.json)
+- Intro docs: [/platzi/getting-started](/platzi/getting-started)

docs/platzi/getting-started/quickstart.md

@@ -0,0 +1,45 @@
+---
+title: Quickstart
+sidebar_position: 2
+description: Run the core Platzi playground operations with curl.
+---
+
+# Quickstart
+
+Run the same operations exposed in the [API playground](/platzi/api-playground).
+
+## 1) List products
+
+```bash
+curl "https://api.escuelajs.co/api/v1/products?offset=0&limit=5"
+```
+
+## 2) List categories
+
+```bash
+curl "https://api.escuelajs.co/api/v1/categories"
+```
+
+## 3) Check if an email is available
+
+```bash
+curl -X POST "https://api.escuelajs.co/api/v1/users/is-available" \
+  -H "content-type: application/json" \
+  -d '{"email":"john@mail.com"}'
+```
+
+## 4) Login to get tokens
+
+```bash
+curl -X POST "https://api.escuelajs.co/api/v1/auth/login" \
+  -H "content-type: application/json" \
+  -d '{"email":"john@mail.com","password":"changeme"}'
+```
+
+## 5) Query locations
+
+```bash
+curl "https://api.escuelajs.co/api/v1/locations?size=3"
+```
+
+Next: [Authentication](/platzi/getting-started/authentication)

docs/platzi/index.md

@@ -0,0 +1,12 @@
+---
+slug: /
+title: Platzi demo docs
+description: Landing page for the Platzi Fake Store demo docset.
+---
+
+# Platzi demo docs
+
+Use this docset to explore a curated set of real, public Fake Store API endpoints.
+
+- Start here: [Getting started](/platzi/getting-started)
+- Run live requests: [API playground](/platzi/api-playground)

docs/platzi/locations/index.md

@@ -0,0 +1,17 @@
+---
+title: Locations
+sidebar_position: 1
+description: Geospatial demo endpoint for store-like location data.
+---
+
+# Locations
+
+Use `GET /locations` for geospatial examples in maps or "stores near me" style demos.
+
+## Example
+
+```bash
+curl "https://api.escuelajs.co/api/v1/locations?size=5"
+```
+
+You can also provide `origin` and `radius` query parameters in the [API playground](/platzi/api-playground).

docs/platzi/navigation.json

@@ -0,0 +1,37 @@
+[
+  {
+    "type": "category",
+    "label": "Getting started",
+    "items": [
+      {"type": "doc", "id": "getting-started/index", "label": "Overview"},
+      {"type": "doc", "id": "getting-started/quickstart", "label": "Quickstart"},
+      {"type": "doc", "id": "getting-started/authentication", "label": "Authentication"},
+      {"type": "doc", "id": "getting-started/error-handling", "label": "Error handling"},
+      {"type": "doc", "id": "getting-started/playground", "label": "Playground guide"}
+    ]
+  },
+  {
+    "type": "category",
+    "label": "Products",
+    "items": [
+      {"type": "doc", "id": "products/index", "label": "Overview"},
+      {"type": "doc", "id": "products/list", "label": "List and paginate"}
+    ]
+  },
+  {
+    "type": "category",
+    "label": "Users",
+    "items": [
+      {"type": "doc", "id": "users/index", "label": "Overview"},
+      {"type": "doc", "id": "users/check-email", "label": "Check email"}
+    ]
+  },
+  {
+    "type": "category",
+    "label": "Locations",
+    "items": [
+      {"type": "doc", "id": "locations/index", "label": "Overview"}
+    ]
+  },
+  {"type": "link", "label": "API playground", "href": "/platzi/api-playground"}
+]

docs/platzi/products/index.md

@@ -0,0 +1,15 @@
+---
+title: Products
+sidebar_position: 1
+description: Products surface used in the Platzi playground.
+---
+
+# Products
+
+The demo playground focuses on list-style product retrieval.
+
+## Included operation
+
+- [List and paginate](/platzi/products/list): `GET /products`
+
+Use the [API playground](/platzi/api-playground) to execute requests and inspect live responses.

docs/platzi/products/list.md

@@ -0,0 +1,21 @@
+---
+title: List and paginate
+sidebar_position: 2
+description: Retrieve product lists with offset and limit.
+---
+
+# List and paginate products
+
+Use `GET /products` with `offset` and `limit`.
+
+## Example
+
+```bash
+curl "https://api.escuelajs.co/api/v1/products?offset=0&limit=10"
+```
+
+## Notes
+
+- `offset` controls how many records to skip.
+- `limit` controls max records returned.
+- Data can change because this is a shared public demo API.

docs/platzi/users/check-email.md

@@ -0,0 +1,23 @@
+---
+title: Check email
+sidebar_position: 2
+description: Validate whether an email can be used for a new account.
+---
+
+# Check email availability
+
+Use `POST /users/is-available` with an `email` payload.
+
+## Example
+
+```bash
+curl -X POST "https://api.escuelajs.co/api/v1/users/is-available" \
+  -H "content-type: application/json" \
+  -d '{"email":"john@mail.com"}'
+```
+
+## Response shape
+
+```json
+{"isAvailable": false}
+```

docs/platzi/users/index.md

@@ -0,0 +1,15 @@
+---
+title: Users
+sidebar_position: 1
+description: User endpoints used in the Platzi playground.
+---
+
+# Users
+
+This docset includes user listing and email availability checks.
+
+## Included pages
+
+- [Check email](/platzi/users/check-email): `POST /users/is-available`
+
+Authentication flows are covered in [Getting started > Authentication](/platzi/getting-started/authentication).

docs/platzi/variables.json

@@ -0,0 +1,3 @@
+{
+  "api_base_url": "https://api.escuelajs.co/api/v1"
+}