Skip to content

docs(openapi): Use more autogenerated response examples#2306

Open
Pijukatel wants to merge 4 commits intomasterfrom
extract-openapi-examples
Open

docs(openapi): Use more autogenerated response examples#2306
Pijukatel wants to merge 4 commits intomasterfrom
extract-openapi-examples

Conversation

@Pijukatel
Copy link
Contributor

@Pijukatel Pijukatel commented Mar 3, 2026 •
edited
Loading

Summary

  • Delete some explicit examples and use auto-generated examples from the schema.
  • Keep explicit examples where it helps:
    • lists, where an autogenerated example would contain just one item
    • specific non-default values. For example, aborted runs will have some specific run status, so returning an autogenerated example run could be confusing

Motivation

  • Remove massive code duplication
  • Preparation for adding undocumented redispatch endpoints, which would otherwise have to repeat the examples again, making the duplication even worse.
  • Manual examples are missing newly added optional fields

Example:
image

Note

Cursor Bugbot is generating a summary for commit 2fe84fe. Configure here.

@Pijukatel Pijukatel changed the title doc(openapi): Extract and re-use common example API responses docs(openapi): Extract and re-use common example API responses Mar 3, 2026
@github-actions github-actions bot added this to the 135th sprint - Tooling team milestone Mar 3, 2026
@github-actions github-actions bot added the t-tooling Issues with this label are in the ownership of the tooling team. label Mar 3, 2026
@apify-service-account
Copy link

apify-service-account commented Mar 3, 2026

Preview for this PR was built for commit 5423956 and is ready at https://pr-2306.preview.docs.apify.com!

@apify-service-account
Copy link

apify-service-account commented Mar 3, 2026

Preview for this PR was built for commit c6d55c21 and is ready at https://pr-2306.preview.docs.apify.com!

@Pijukatel Pijukatel added the adhoc Ad-hoc unplanned task added during the sprint. label Mar 3, 2026
@Pijukatel Pijukatel changed the title docs(openapi): Extract and re-use common example API responses docs(openapi): Use more autogenerated response examples Mar 3, 2026
@Pijukatel Pijukatel marked this pull request as ready for review March 3, 2026 15:50
@apify-service-account
Copy link

apify-service-account commented Mar 3, 2026

Preview for this PR was built for commit 2fe84fef and is ready at https://pr-2306.preview.docs.apify.com!

@janbuchar
Copy link
Contributor

janbuchar commented Mar 3, 2026

  • Avoid risk of rotting examples (autogenerated examples are compliant with the latest specification out of the box)

Is this a genuine concern? I'd expect that examples will be validated against the spec by at least one of our openapi linters

janbuchar
janbuchar reviewed Mar 3, 2026
View reviewed changes
apify-api/openapi/paths/actor-runs/actor-runs.yaml Outdated
defaultRequestQueueId: soowucklrmDzKpA8x
examples:
example:
$ref: ../../components/schemas/actor-runs/ListOfRunsResponseExample.yaml
Copy link
Contributor

@janbuchar janbuchar Mar 3, 2026

Choose a reason for hiding this comment

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

This is a very weird place to put a reusable example. There is a dedicated components.examples section defined by the OpenAPI spec- https://spec.openapis.org/oas/v3.1.0#components-object

Copy link
Contributor Author

@Pijukatel Pijukatel Mar 3, 2026

Choose a reason for hiding this comment

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

Moved to examples. I would structure that folder later, when there are more examples.

@Pijukatel
Copy link
Contributor Author

Pijukatel commented Mar 3, 2026

  • Avoid risk of rotting examples (autogenerated examples are compliant with the latest specification out of the box)

Is this a genuine concern? I'd expect that examples will be validated against the spec by at least one of our openapi linters

You are right. Examples are validated. Only the new optional fields will be missing.

@Pijukatel Pijukatel force-pushed the extract-openapi-examples branch from 85c27e9 to 98224c5 Compare March 3, 2026 16:22
@Pijukatel Pijukatel requested a review from janbuchar March 3, 2026 16:23
@apify-service-account
Copy link

apify-service-account commented Mar 3, 2026

Preview for this PR was built for commit 85c27e91 and is ready at https://pr-2306.preview.docs.apify.com!

janbuchar
janbuchar approved these changes Mar 3, 2026
View reviewed changes
Copy link
Contributor

@janbuchar janbuchar left a comment

Choose a reason for hiding this comment

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

LGTM.

@apify-service-account
Copy link

apify-service-account commented Mar 3, 2026

Preview for this PR was built for commit 98224c5b and is ready at https://pr-2306.preview.docs.apify.com!

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

Reviewers

@janbuchar janbuchar janbuchar approved these changes

@fnesveda fnesveda Awaiting requested review from fnesveda fnesveda is a code owner

Assignees

@Pijukatel Pijukatel

Labels

adhoc Ad-hoc unplanned task added during the sprint. t-tooling Issues with this label are in the ownership of the tooling team.

Projects

None yet

Milestone

135th sprint - Tooling team

Development

Successfully merging this pull request may close these issues.

3 participants

@Pijukatel @apify-service-account @janbuchar