Skip to content

fix: standardize nullable refs and correct array items syntax #1996

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom
Merged
merged 1 commit into from
Oct 10, 2025
Merged

fix: standardize nullable refs and correct array items syntax #1996

merged 1 commit into from
Oct 10, 2025

Conversation

@bliuchak
Copy link
Contributor

@bliuchak bliuchak commented Oct 10, 2025 •
edited
Loading

This PR fix two places where docs used non-standard (according to OpenAPI 3.0) spec.

Why? I was playing with oapi-codeget tool for generation Go client from openapi.yaml. Without these changes I wasn't able to generate it.

I got these errors:

  1. Caused by incorrect ProxyGroup ref

    $ go tool oapi-codegen openapi.yaml
error loading swagger spec in openapi.yaml
: failed to load OpenAPI specification: failed to unmarshal data: json error: invalid character 'o' looking for beginning of value, yaml error: error unmarshaling JSON: while decoding JSON: json: cannot unmarshal array into field Schema.items of type openapi3.Schema

  2. Caused by incorrect nullable ActorDefinition

    $ go tool oapi-codegen openapi.yaml
error generating code: error generating type definitions: error generating Go types for component schemas: error converting Schema Build to Go type: error generating Go schema for property 'actorDefinition': error generating type for oneOf: error resolving primitive type: unhandled Schema type: &[null]

Details about oapi-codegen:

go tool oapi-codegen -version
github.com/oapi-codegen/oapi-codegen/v2/cmd/oapi-codegen
v2.5.0

Places for verification:

@bliuchak bliuchak requested a review from janbuchar as a code owner October 10, 2025 10:13
@bliuchak bliuchak added the bug Something isn't working. label Oct 10, 2025
@bliuchak bliuchak requested a review from fnesveda as a code owner October 10, 2025 10:13
@github-actions github-actions bot added the t-core-services Issues with this label are in the ownership of the core services team. label Oct 10, 2025
@apify-service-account
Copy link

apify-service-account commented Oct 10, 2025

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

@bliuchak bliuchak added the adhoc Ad-hoc unplanned task added during the sprint. label Oct 10, 2025
fnesveda
fnesveda approved these changes Oct 10, 2025
View reviewed changes
Copy link
Member

@fnesveda fnesveda left a comment

Choose a reason for hiding this comment

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

Cool, good catch 🙂

@bliuchak bliuchak merged commit 3ce9107 into master Oct 10, 2025
14 of 15 checks passed
@bliuchak bliuchak deleted the fix/nullable branch October 10, 2025 11:22
@raethlo raethlo added the validated Issues that are resolved and their solutions fulfill the acceptance criteria. label Oct 13, 2025
@bliuchak bliuchak mentioned this pull request Nov 11, 2025
Merged
bliuchak added a commit that referenced this pull request Nov 14, 2025
@bliuchak
feat(ci): validate OpenAPI spec by generating and building Go client (#…
e965493 
…2078)

This PR follows up on #2000.

**What**
Adds automated validation of our OpenAPI specification by generating a
Go client from the spec and verifying that the generated code compiles
successfully.

**Why**
- Fast feedback loop: Catch OpenAPI spec issues immediately by
validating that client generation and compilation succeed.
- Spec compliance: Ensure our OpenAPI spec adheres to the standard by
using it in a real-world scenario (client generation + build).
- Foundation for multi-language clients: While the generated code is
currently discarded after validation, this establishes the
infrastructure to generate and publish clients for multiple languages
(e.g., TypeScript, Python) in the future.

This approach provides validation beyond just schema checking - if the
generated Go client builds successfully, we can be confident the spec is
both valid and practical to use.

**Folder structure**
The repository structure follows these conventions:
- `codegen/` - Contains only generated code (files, folders, etc.) and
should never be modified manually.
- `oapi-codegen-go/` - Follows the naming pattern [tool-name]-[language]
where:
  - `oapi-codegen` is the code generation tool.
  - `go` is the target language.

This convention makes it straightforward to add support for additional
tools and languages in the future (e.g., openapi-generator-typescript,
oapi-codegen-python).

**Examples**
- This is an
[example](https://github.com/apify/apify-docs/actions/runs/19227338449/job/54957493226?pr=2078)
of successfull action.
- This is an
[example](https://github.com/apify/apify-docs/actions/runs/19227226704/job/54957143384?pr=2078)
of failed action (can generate Go client but compilation failed due to
invalid OpenAPI spec).

**Refs**
- #1996
- #2057

<!-- CURSOR_SUMMARY -->
> [!NOTE]
> Adds a CI job that builds the OpenAPI spec, generates a Go client via
oapi-codegen, and compiles it, with accompanying codegen config and
ignores.
> 
> - **CI/CD (`.github/workflows/openapi.yaml`)**:
> - **New job `validate-go-codegen`**: Builds OpenAPI YAML, installs
`oapi-codegen`, generates Go client, and builds it with Go 1.25.
>   - Update existing build to Node.js `24` and run `redoc:test`.
> - **Go client codegen setup**:
>   - Add `codegen/oapi-codegen-go/go.mod` declaring tool and deps.
> - Add `codegen/oapi-codegen-go/oapi-codegen.yaml` configuring
client/model generation to `generated/client.gen.go`.
> - **Repo housekeeping**:
> - Update `.gitignore` to exclude `codegen/*/generated/` and
`codegen/*/go.sum`.
> 
> <sup>Written by [Cursor
Bugbot](https://cursor.com/dashboard?tab=bugbot) for commit
e657bac. Configure
[here](https://cursor.com/dashboard?tab=bugbot).</sup>
<!-- /CURSOR_SUMMARY -->
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@fnesveda fnesveda fnesveda approved these changes

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

Assignees

@bliuchak bliuchak

Labels

adhoc Ad-hoc unplanned task added during the sprint. bug Something isn't working. t-core-services Issues with this label are in the ownership of the core services team. validated Issues that are resolved and their solutions fulfill the acceptance criteria.

Projects

None yet

Milestone

125th sprint - Core Services team

Development

Successfully merging this pull request may close these issues.

5 participants

@bliuchak @apify-service-account @fnesveda @raethlo