How would you structure API docs and tools for reference and narrative?

What's really being asked

Whether you understand that API documentation is not monolithic. Interviewers want to see that you recognize the split between structured, machine-generated reference documentation and human-authored narrative content, and that you know how to integrate both into a cohesive developer experience. They are looking for familiarity with the OpenAPI ecosystem, docs-as-code workflows, and information architecture that serves developers at different skill levels.

The full answer

First, a two-pillar content model. On one side, reference documentation generated from an OpenAPI specification using tools like Swagger UI, Redocly, or Stoplight. This covers endpoints, methods, parameters, request and response schemas, and authentication details. On the other side, narrative and conceptual docs written by hand: a product overview, a getting-started tutorial, authentication and authorization guides, status and error code explanations, rate limiting details, quick references, and a glossary. Second, a unified delivery strategy. Use a docs-as-code approach where narrative content lives in Markdown under version control, and a static site generator pulls in both the hand-written guides and the auto-generated OpenAPI reference to publish a single hybrid site. Third, audience-aware sequencing. Beginners need a curated path, starting with a product overview and a step-by-step tutorial that makes a real API call, before they ever see a raw endpoint reference. Experienced developers want to jump straight to the OpenAPI-generated specs or a quick reference. Fourth, tooling specifics. Mention authoring the OpenAPI spec in YAML or JSON, possibly using Stoplight for visual design, then publishing with Swagger UI for interactive exploration or Redocly for polished rendering, while the narrative layer might be built with a static site generator that supports custom pages.

The mistakes people make

Suggesting that Swagger or OpenAPI alone solves the documentation problem. Auto-generated reference docs list endpoints but do not explain why a developer should care, how to get an API key, or how to handle pagination. Another red flag is proposing a fully manual documentation process with no OpenAPI spec, which signals unfamiliarity with modern API doc standards. Proposing PDF or Word-based publishing instead of web-based, version-controlled docs is also a negative signal for technical audiences.

What usually comes next

How do you keep the OpenAPI spec in sync with the implementation? How do you handle versioning when the API changes? What is your strategy for testing code samples and ensuring they still work? How do you measure whether developers are successfully onboarding versus getting stuck?

A concrete example

For a weather API, you would maintain an openapi.yaml file describing the current conditions endpoint, its parameters like latitude and longitude, and its JSON response schema. Swagger UI renders this into an interactive reference page where developers can execute requests. Alongside that, you write a getting-started tutorial that walks a beginner through signing up for a key, making their first curl call, and parsing the JSON response. Both the tutorial and the Swagger UI output are published through the same static site generator under a single domain, with cross-links between the tutorial and the reference so a beginner can move from narrative to spec seamlessly.