# Customizing Endpoint Documentation

This guide explains how to add and override endpoint documentation using a JSON file.

## Overview

drf-to-mkdoc generates endpoint documentation from the OpenAPI schema produced by DRF Spectacular. You can refine and extend that documentation using a `custom_schema.json` file.

By default the project looks for:

- `docs/configs/custom_schema.json`

You can change the location via the `CUSTOM_SCHEMA_FILE` setting in `DRF_TO_MKDOC`.

## File format

The file is a JSON object keyed by `operationId`. Each entry can override a subset of fields in the OpenAPI operation and optionally append to list fields.

Supported keys per operation:
- `description` (string)
- `parameters` (array of OpenAPI Parameter objects)
- `requestBody` (OpenAPI RequestBody object)
- `responses` (OpenAPI Responses object)
- `append_fields` (array of keys to append instead of replace; currently only applies to list-typed fields)

Example (adapted):

```json
{
  "clinic_panel_appointments_available_appointment_times_list": {
    "responses": {
      "200": {
        "description": "List of available appointment times grouped by date.",
        "content": {
          "application/json": {
            "schema": {
              "type": "array",
              "items": {
                "type": "object",
                "properties": {
                  "date": {
                    "type": "string",
                    "description": "Date in DATE_FORMAT"
                  },
                  "time_slots": {
                    "type": "array",
                    "items": {
                      "type": "object",
                      "properties": {
                        "start_datetime": {
                          "type": "string",
                          "description": "Start datetime in DATETIME_FORMAT"
                        },
                        "end_datetime": {
                          "type": "string",
                          "description": "End datetime in DATETIME_FORMAT"
                        }
                      },
                      "required": ["start_datetime", "end_datetime"]
                    },
                    "description": "Available time slots for the date"
                  }
                },
                "required": ["date", "time_slots"]
              }
            }
          }
        }
      }
    }
  }
}
```

## Query parameter metadata

When adding a query parameter (i.e., `{"in": "query"}`), include a `queryparam_type` so it is categorized properly in the generated docs. Supported values:

- `search_fields`
- `filter_fields`
- `ordering_fields`
- `filter_backends`
- `pagination_fields`

If missing or invalid, generation raises an error to help you correct the entry.

## How it is applied

- The generator loads the in-memory OpenAPI schema
- For each `operationId` found in `custom_schema.json`, it:
  - Locates the corresponding operation in the schema
  - Replaces supported fields by default
  - Appends items instead of replacing, for fields listed in `append_fields` (e.g., `parameters`)
- The merged schema is then used to produce endpoint markdown files

## Finding operationIds

Operation IDs are generated by DRF Spectacular. To discover them:
- Open the generated API endpoint pages; each page includes the operationId
- Or inspect your OpenAPI JSON/YAML (via the schema endpoint or export)

## Tips

- Keep `custom_schema.json` in version control so the whole team benefits
- Start small: add descriptions first, then parameters and examples
- Use `append_fields` when you want to keep auto-generated items and add your own