Unclear API documentation delays integration testing
A software company with 3,200 employees runs more than 220 services. Of around 1,400 API documents per year, many are incomplete at project start and delay integrations.
- Technology
- Software Development
Key metric
Time per API document
3 h1.5h
Average time spent per API document
At a glance
Starting point
With around 3,200 employees, the software company runs more than 220 services across several product lines. About 1,000 features are delivered each year, roughly 70 percent of which involve new or changed APIs. On average, each API produces two documents for internal and external consumers, around 1,400 API documents a year. OpenAPI specifications exist for most REST services, but some are maintained by hand and drift from the code. The explanatory documentation is maintained by about 18 product teams in different tools, from wikis and Markdown files in the repository to PDF attachments. Each API description has so far taken an average of three hours for writing, coordination and upkeep, around 4,200 hours a year in total.
- 1,400
- API documents per year
- 4,200 h
- documentation effort per year
The challenge
API documentation is often incomplete or outdated by the time integration projects start. Endpoints are listed, but examples, error codes or edge cases are missing. Different teams use different formats and terms, which makes reuse harder. Integration partners come back with questions because the documentation doesn't show which fields are mandatory or which status codes occur in which situations. QA teams have to piece information together from tickets, code and old documents. Integration and end-to-end tests start late because clarifications take several rounds of coordination.
Typical symptoms in the organization
Why this remained unsolved
The problem was known but accepted as an unavoidable consequence of a high pace of change. There were style guides and an API portal, but maintaining them was manual and time-consuming. Generation from code comments and OpenAPI specifications only covered signatures and schemas, not examples, edge cases or integration notes. A dedicated project to standardize the documentation would have tied up several months of development and QA capacity and was therefore repeatedly postponed in favor of business features.
Our solution
Together with the development teams, an assistance system was introduced that makes the machine-readable specification the authoritative source: OpenAPI for REST interfaces and AsyncAPI for event-driven interfaces. The system first reconciles the specification with code and tests, fills in missing details and lints it against the API style guide. Building on this, it creates a documentation draft with clear sections on endpoints, parameters, examples, error codes, edge cases and integration notes. Developers start from their usual workflow, for example from the repository or the API portal. Sample requests and responses are validated against the specification and contract tests before they are added to a draft. The system flags uncertainties and points to similar existing APIs. QA and integration partners provide feedback that flows into new versions. The result is a consistent standard without forcing teams into a new tool.
Where generative AI comes in
Generative AI analyzes code, tests, commit messages, tickets and existing API documents and, based on the specification, writes structured API descriptions with examples and error cases. It understands unstructured descriptions, carries patterns over from similar APIs, names edge cases and open questions, and improves drafts iteratively with feedback. Checking the specification and examples remains deterministic and is not left to the language model.
- OpenAPI and AsyncAPI specifications as the authoritative source, reconciled with code and tests, completed and linted against the style guide
- Integration with repositories and the API portal to automatically pull in and link signatures, comments and existing descriptions
- Connection to the ticketing system and test suites so that relevant user stories, acceptance criteria and test cases feed into the documentation
- Interactive documentation assistant that flags missing details, asks targeted questions and suggests sample requests that are automatically validated against the specification and contract tests
- Review mode with role-based access for QA and integration partners that bundles comments, highlights changes and records approvals for published API documents
- Feedback loop that analyzes accepted and rejected suggestions and uses them to adapt prompts, the example collection and retrieval to team conventions, without retraining the model
Rollout in API development
Current-state analysis
Survey of typical API documents, existing OpenAPI specifications, integration processes and style guides in selected product teams, including time spent and pain points.
Pilot integration
Connecting the assistance system to repositories, the API portal and the ticketing system for two teams, defining the target structure for API documents and a first pilot run.
Fine-tuning
Jointly refining structure, tone and the example collection based on real pilot documents and feedback from QA and integration partners.
Rollout
Gradual rollout to further teams, training in short sessions and adapting the approval processes in the API portal to the new documentation workflow.
Monitoring
Ongoing analysis of usage rate, integration queries and quality incidents, with regular adjustment of prompts, examples and retrieval to new guidelines and API patterns.
Measured: after six months in production
Period: after six months in production.
| Metric | Value | Basis |
|---|---|---|
| Time per API documentKey metric | from 3 hours to 1.5 hours per document | Time logs in the pilot teams, before/aftermeasured |
| Integration queries per API | Down from an average of 5 to 3 queries | System measurementmeasured |
| Failed integration tests caused by documentation errorsQuality metric | Share falls from around 30% to 20% | Sample of failed testsestimated |
| Usage rate | Around 75% of new API documents start with a draft from the assistant | System measurementmeasured |
| Quality incidents | 3 incorrect examples in approved documents, each corrected within one working day | Escalation ticketsmeasured |
Cost-effectiveness
The solution only delivers its full benefit if teams use the assistant consistently and accept the specification in the API portal as the central source. For very small or short-lived APIs, the extra step can feel like overhead. API portals and coding assistants now offer some of these building blocks as standard features. The actual effort depends on how much of that can be used.
Integration and operation
Transferability
The approach suits any situation where interfaces or products have to be documented regularly but content varies widely and contains a lot of free text. Combining structured templates, generative drafts and integrated reviews can speed up documentation processes in other domains as well, without introducing rigid tools. What matters is a clear framework for which content still has to be reviewed and approved by people.
A similar case in your organization? Let's talk.
Briefly describe your process. We'll get back to you with an initial assessment of whether the pattern can be transferred and what it would realistically take.