Skip to content

docs(openapi): improve docs for session model and default session endpoints#5031

Open
akshay-kumar-bm wants to merge 2 commits intogoogle:mainfrom
akshay-kumar-bm:docs/openapi-session-endpoint-docs-update
Open

docs(openapi): improve docs for session model and default session endpoints#5031
akshay-kumar-bm wants to merge 2 commits intogoogle:mainfrom
akshay-kumar-bm:docs/openapi-session-endpoint-docs-update

Conversation

@akshay-kumar-bm
Copy link
Copy Markdown

Description

This PR improves the generated OpenAPI/Swagger documentation for session
management by adding clearer endpoint metadata and richer schema docs
(descriptions + examples).

What changed

  • Session model docs: add field descriptions/examples for Session so the API
    schema is self-explanatory.
  • Default session endpoints: improve OpenAPI docs for the built-in session
    management routes (create/get/list/update/delete sessions + events/artifacts
    where applicable) so request/response shapes and common errors are clearer.
  • System endpoints: enhance docs for basic endpoints like /health, / version,
    and /list-apps (where present in this server), including clearer summaries
    and error notes.

Why

The OpenAPI output was correct but lacked enough context (field meanings,
examples, and expected error cases) for users reading Swagger UI or generating
clients.

Testing

Documentation-only change (OpenAPI metadata / schema docs).

  • Unit tests: Not run.
  • Manual check: Confirm Swagger UI shows the new descriptions/examples for
    session-related schemas and endpoints.

Notes

  • Includes an empty commit (chore: rerun CI) to re-trigger GitHub Actions
    without changing code.

Checklist

  • Read CONTRIBUTING.md.
  • Self-reviewed the change.
  • Added/updated unit tests (N/A for doc-only change).
    • Ran unit tests locally (not run for doc-only change).

@akshay-kumar-bm
Copy link
Copy Markdown
Author

Here some screenshort compare origin and updateing doc

image image image

@adk-bot adk-bot added the documentation [Component] This issue is related to documentation, it will be transferred to adk-docs label Mar 27, 2026
@rohityan rohityan self-assigned this Mar 30, 2026
@rohityan rohityan added web [Component] This issue will be transferred to adk-web and removed web [Component] This issue will be transferred to adk-web labels Mar 30, 2026
@@ -1076,10 +1215,47 @@ async def get_session_trace(session_id: str) -> Any:
@app.get(
"/apps/{app_name}/users/{user_id}/sessions/{session_id}",
Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

having a tags=["Sessions"] would be helpful.

@rohityan
Copy link
Copy Markdown
Collaborator

Hi @akshay-kumar-bm , Thank you for your contribution! We appreciate you taking the time to submit this pull request. Please fix formatting errors by running autoformat.sh. Also please address the review comments.

@rohityan rohityan added the request clarification [Status] The maintainer need clarification or more information from the author label Mar 30, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

documentation [Component] This issue is related to documentation, it will be transferred to adk-docs request clarification [Status] The maintainer need clarification or more information from the author

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants