API Features documented from source code: the endpoint header

Open
  • Is something wrong?
#110 0 comments 0 reactions 0 assignees View on GitHub

Maintainers usually reply within 1 day

Nobody has claimed this yet.

Assessment

Difficulty
5/5
Estimated time
Over a week
Newbie friendliness
12/100
Issue type
Feature
Clarity
Needs clarification
Activity status
Active
Tech stack
markdown, python, typescript
Domain
backend-api-design, documentation, tooling

Research direction

Start with the PageObject header section of docs/reference/authoring-formats.md and the Feature entry in docs/reference/glossary.md, since the proposed endpoint header copies that model. The first task is the spike, an operator-run survey of how ABSA repositories define endpoints and document contracts, and it is not a code change for a newcomer. Done means the spike reports a shape inventory and confirms or corrects the header design.

Written by the indexing model from the issue text.

Description

type:epic
Background

A project documented in source code cannot document an API Feature today. Source-code headers exist only for
.feature files (User Story, Functionality) and PageObjects (the UI Feature), and living-doc-collector-gh's
doc-source mode reads PageObjects from .ts files only. The canon therefore sends API Features to GitHub Issues or
Azure DevOps, and a feature_dependencies target in a source-code project gives UNRESOLVED_RELATION, which is
expected today (docs/reference/glossary.md, Feature).

A design was drafted in 2026-09 and deferred:

  • a LIVING DOC — comment block directly above the endpoint or handler definition, never at the top of a file, any
    number per file;
  • the PageObject model: one full header per API Feature, cross-reference headers (parent-feat:) on the others;
  • new keys endpoint: and handler:, not route: and page-object: (clarity over reuse);
  • no stub-reason:, and no rule on how many Functionalities one endpoint has; the author decides.

A spike comes first and may change it. Its first finding: atum-service defines endpoints as Tapir values inside an
object, not as annotated methods, so "above the method" is not general enough.

Goals
  • A backend service documents its API Features in its own source code, next to the endpoints.
  • doc-source mines the header from the file types the spike names, and the Feature's endpoints reach the documents.
  • feature_dependencies resolve in a source-code project.
  • The agentic layer writes and maintains the header, and keeps feature_dependencies on the Feature.
Subtasks

In landing order. Each child is drafted when the previous one has merged.

  • living-doc (Spike form): a survey across ABSA repositories, run on local clones plus internal ones as an
    operator run that reports a shape inventory only. It covers the languages and file types, how an endpoint or
    event handler is defined (annotations, route tables, Tapir values), the contract documentation already in use
    (OpenAPI and others), the comment forms per file type, and discovery and exclusions. It ends with the header
    design confirmed or corrected.
  • living-doc: the canon. The endpoint header in docs/reference/authoring-formats.md and the glossary, an
    example in docs/examples/, and examples_check rules for it.
  • living-doc agentic layer: skills write and update the header, and feature_dependencies moves onto the
    Feature, with evals.
  • living-doc-utilities: the parser for the header and an EndpointRef beside PageRef, plus the rendering
    rules for endpoints; released as a minor.
  • living-doc-collector-gh: doc-source reads more file types and mines the header.
  • living-doc-toolkit and living-doc-generator-markdown: endpoints carried and rendered, if the contract
    change needs it.
  • living-doc-testbed: an API Feature in source code. living-doc: snapshots, a milestone run and the
    release.
Related / References
  • docs/reference/glossary.md (Feature, feature_dependencies, surface_type), docs/reference/authoring-formats.md
    (PageObject header: full and cross-reference).
  • living-doc-utilities docs/authoring/parsers.md.
Dominant language
Python
Stars
0
Forks
0
Avg merge
6h 14m
Merged PRs (30d)
27

Getting set up

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from AbsaOSS/living-doc

All issues in AbsaOSS/living-doc

Similar issues

More Python issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.