Skip to content

Replace stale README API docs with published Postman collection #145

Description

@Dejmenek

Summary

Remove the stale, hand-maintained API reference from README.md and replace it with a properly maintained, published Postman collection + auto-generated docs.

Background

README.md currently contains a large "Detailed API Documentation" section (queries, mutations, request/response examples) that is manually written and drifts out of sync with the actual GraphQL schema. This should be replaced with a Postman collection that is the source of truth, with docs auto-generated from it and published via Postman's built-in Publish feature.

Tasks

  • Remove the stale "Detailed API Documentation" section from README.md (Authentication, Tournament Management, Participant Management, Bracket Management, Queries subsections and their request/response examples)
  • Build a new Postman collection from scratch covering all current queries and mutations:
    • Auth: registerUser, loginUser, me, refresh token / logout mutations
    • Tournaments: createTournament, updateTournament, deleteTournament, tournaments, tournamentById
    • Participants: addParticipant, joinTournament
    • Brackets/Matches: generateBracket, play, updateRound, matchesForRound
  • Add a collection-level description covering what the API does and how to use the collection
  • Document authorization in the collection: JWT bearer auth setup, how to obtain a token via loginUser, and which requests require auth
  • Add per-request descriptions, example variables, and example responses (success + typed error cases) for each query/mutation
  • Generate API documentation from the collection using Postman's built-in doc templates
  • Publish the collection and documentation using Postman's Publish feature
  • Update README.md to link to the published Postman documentation in place of the removed section

Acceptance Criteria

  • README.md no longer contains inline hand-written API request/response examples
  • README.md links to the published Postman docs
  • Postman collection includes description, auth setup, and all current queries/mutations with examples
  • Postman docs are published and publicly accessible via the generated link

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

Labels

documentationImprovements or additions to documentation

Projects

No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions