Testing Routes with Docusaurus

This README explains how to configure servers and authentication (Bearer JWT and custom token header) in your OpenAPI/Swagger setup, and how to test API routes in the docs using the Request panel and Send API Request (or the curl tab to copy a command).

---

1. Configuring servers and authentication (Swagger/OpenAPI)

In your API, define servers and securitySchemes so documentation and the API Explorer know the base URLs and how to send credentials:

javascript
  const swaggerOptions = {
    definition: {
      openapi: '3.0.0',
      info: {
        title: 'API Mobilemed',
        version: '1.0.0',
        description: 'Documentação da API Mobilemed',
      },
      servers: [
        { url: 'http://localhost:9001', description: 'Local' },
        { url: 'https://gateway-homolog.mobilemed.com.br', description: 'Homolog' },
      ],
      components: {
        securitySchemes: {
          tokenHeader: {
            type: 'apiKey',
            in: 'header',
            name: 'token',
            description: 'Token',
          },
          bearerAuth: {
            type: 'http',
            scheme: 'bearer',
            bearerFormat: 'JWT',
            description: 'Token JWT (Authorization: Bearer)',
          },
        },
      },
      security: [
        { tokenHeader: [] },
        { bearerAuth: [] },
      ],
    },
    apis: ['./routes/*.js', './docs/swagger/*.js'],
  };

• servers: Base URLs for the API (e.g. Local, Homolog). The API Explorer uses these as the base for each request.
• securitySchemes:
  • tokenHeader: API key sent in the token header.
  • bearerAuth: JWT sent in the Authorization: Bearer <token> header.
• security: Applies bearerAuth by default to all operations (you can override per route).

---

2. Testing routes in Docusaurus (Request panel and Send API Request)

The docs site uses docusaurus-theme-openapi-docs, which adds an API Explorer on each OpenAPI endpoint page. You can send requests from the browser and get a ready-to-use curl command.

Where to find it

1. Open any API route page (e.g. under OpenAPI → Legacy API → Exam or User Management).
2. On that page you’ll see:
   • The method and path of the endpoint.
   • A Request section with:
     • Server dropdown (if your OpenAPI spec defines multiple servers).
     • Auth fields (Bearer token and/or custom token header).
     • Body or parameters (path, query, headers) when the endpoint needs them.
     • Send API Request button.
   • Code tabs (including curl) and a Response area.

How to test a route with the Request panel and Send API Request

1. Select the server in the Request section (e.g. Local or Homolog). This sets the base URL for the call.
2. Set authentication in the Auth fields:
   • Bearer JWT: enter your token in the Bearer field.
   • Custom token: enter the value in the token field (if your spec defines tokenHeader).
3. Fill the request:
   • For GET/query: fill any query or path parameters shown in the form.
   • For POST/PUT/PATCH: fill the Request body (e.g. JSON in the body editor).
4. Click Send API Request. The site sends the request to the selected server with the chosen auth and body; the Response area shows status, headers, and body.
5. To run the same call from the terminal: open the curl tab in the code samples. The theme generates a curl command from the current server, auth, and parameters; copy it and run it in your terminal.

The Send API Request button only appears when the OpenAPI spec defines servers. If you don’t see it, check that your spec includes a servers array (see §1).

---

3. Generating the token automatically (🔑 Gerar Token de Acesso)

To avoid pasting a JWT manually into the Auth field on every page, the docs site adds a custom 🔑 Gerar Token de Acesso button on top of every API Explorer (see src/theme/ApiExplorer/index.tsx). It performs the login against the Mobilemed authentication endpoint, stores the token, and fills the Auth inputs for you.

How it works

1. The button is rendered above the OpenAPI Explorer on every endpoint page.
2. Clicking 🔑 Gerar Token de Acesso opens a small inline form with Email and Senha fields.
3. On Login, the wrapper sends a POST to ${AUTHENTICATION_URL}/authenticate with:

   json
   { "email": "<email>", "senha": "<password>" }

4. The response returns the JWT in the token response header. The wrapper:
   • Saves token, email, and password to localStorage (so the token persists across reloads and pages).
   • Shows a success notification (Token gerado com sucesso!) or an error notification (Erro no login).
5. A MutationObserver watches the page and auto-fills every Auth input (e.g. the token / Authorization fields) inside the API Explorer’s Auth section with the generated token. Username/Password inputs of HTTP Basic schemes are skipped.
6. After that, you can click Send API Request normally — the request will go out already authenticated.

Configuration

The button calls the URL defined by the AUTHENTICATION_URL environment variable (exposed via Docusaurus’s customFields / process.env). Set it in your .env (see .env.local.example):

bash
AUTHENTICATION_URL=https://gateway-homolog.mobilemed.com.br/portal-api/

If AUTHENTICATION_URL is missing, the login request will fail and you’ll see the Erro no login notification.

Tips

• The token is stored in localStorage under the key token, so it stays valid across page navigation and reloads until it expires.
• To log out / use a different account, open the browser DevTools → Application → Local Storage and remove the token, email, and password entries (or just click the button again and submit new credentials).
• If your endpoint uses a different security scheme name (not tokenHeader / bearerAuth), the auto-fill still works as long as the field is rendered inside the Auth section of the Explorer — the wrapper fills every input that is not labeled Username or Password.

---

Summary

Use the Request panel on each endpoint page → select server → click 🔑 Gerar Token de Acesso (or paste a token manually) → fill body/params → click Send API Request to test in the browser, or open the curl tab to copy the command.