Skip to content

Feedback Files

feedback.json files document repairs and improvements made to OpenAPI specs: what changed, why, and when.

They provide: - Documentation — audit trail of fixes - Prevention — avoid reintroducing past issues

Schema

[
  {
    "repaired_file": "openapi.json",
    "repairs": [
      {
        "issue": {
          "message": "string",
          "level": "error|warning|improvement",
          "location": { "jsonPath": "string" }
        },
        "action_taken": "string",
        "source": "human|LLM-suggestion|automated-tool",
        "timestamp": "ISO 8601 timestamp"
      }
    ]
  }
]
````

**Location**
data/apis/openapi////feedback.json 
**Example**

```json
[
  {
    "repaired_file": "openapi.json",
    "repairs": [
      {
        "issue": {
          "message": "Security scheme description incomplete",
          "level": "warning",
          "location": { "jsonPath": "#/components/securitySchemes/basicAuth/description" }
        },
        "action_taken": "Clarified API key usage with basic auth",
        "source": "human",
        "timestamp": "2025-05-23T09:50:50.000000"
      }
    ]
  }
]

Best practices

  • Keep messages specific and actionable
  • Use accurate jsonPath pointers
  • Prefer small, frequent repair records
---

# 🔧 Update navigation (`mkdocs.yml`)

Add a **Public APIs** node under **Reference**:

```yaml

🔁 Cross‑links to add/update (nice-to-haves)

  • getting-started/api-search.md Add a “See also: Public APIs – Overview” link near the top so users understand API Search is backed by the OSS dataset.

  • guides/add-api-integration.md & guides/create-agent-workflows.md Add a small “Where does this live?” box pointing to reference/public-apis/oak-structure.md.

  • community/contributing.md Under “Project‑Specific Notes,” add a bullet for Public APIs linking to reference/public-apis/overview.md.

This setup gives you a clean story:

  • Getting started = how to use it (API Search)
  • Guides = how to contribute content
  • Reference → Public APIs = what the OSS dataset is, how it’s structured, and how it stays high‑quality

If you want, I can also fold the repo’s README highlights (OAK.md, STRUCTURE.md, FEEDBACK-FILES.md) into those pages with small “Edit on GitHub” links so contributors jump straight to the right file.