OpenAPI specs across feature folders

[harikrishnan83]

Hi all 👋,

It is great to see that Spec Kit generates an OpenAPI spec for each feature, super helpful for driving development. One challenge I have noticed though is that these specs end up fragmented across different folders (the OpenAPI specs are under each spec folders like 001-product-listing-page, 002-product-display-page, etc.). This also leads to duplication.

In my frontend–backend apps, I have been experimenting with keeping a unified OpenAPI spec at the repo root as the API contract. This helps me check backward compatibility as part of /plan on the OpenAPI spec to make sure new features do not break existing features. Excerpt from my plan-template.md

## Phase 1: Design & Contracts
*Prerequisites: research.md complete*

1. **Extract entities from feature spec** → `data-model.md`:
   - Entity name, fields, relationships
   - Validation rules from requirements
   - State transitions if applicable

2. **Analyze existing project structure and API contracts**:
   - Check for existing backend/ and frontend/ directories at repository root
   - Check if OpenAPI spec exists at repository root
   - If existing projects found: Plan incremental updates to existing codebase
   - If existing spec found: Analyze whether existing operations can support this feature
   - If reuse possible: Document which existing endpoints/schemas to use

Here is my article on this - https://www.linkedin.com/pulse/spec-driven-development-beyond-first-feature-api-design-krishnan--lbyec. Would love to hear your thoughts and feedback!

Curious if others have run into the same, do you stick with fragmented per-feature specs, or do you consolidate them into a single spec over time?

UPDATE: More detailed walkthrough in this article - https://www.linkedin.com/pulse/spec-driven-development-api-design-first-github-kit-mcp-krishnan--ywx6c.