feat: scaffold initial repo structure, docs, and CI - #1
Merged
Conversation
Add the openapi/<version>/<api>/ layout for versioned spec fixtures, with the Petstore OpenAPI 3.1 spec as the first real example. v3.0 and v3.2 are scaffolded empty pending further examples.
Document the repo's purpose, directory conventions, and CI, and add the dexpace wordmark for branding consistency with the morphic repo. Also records the design decisions behind the scaffold, including the provenance check and fix applied to the seed Petstore spec.
Lint every push and PR: yamllint for YAML syntax, jq for JSON syntax, and openapi spec validate (the same OpenAPI parser morphic itself depends on) for structural validity of every spec file. Release every push to main: bundle the spec directories into a tarball and publish it as a GitHub release tagged with the commit SHA, so there's one release per merged commit.
Pin the third-party release action to its exact commit rather than the mutable v3 tag, so the workflow can't be affected if that tag is ever repointed upstream.
OmarAlJarrah
changed the title
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
openapi/<version>/<api>/directory layout for versioned spec fixtures, seeded with the Petstore OpenAPI 3.1 spec as the first real example (v3.0/v3.2scaffolded empty for now).lint.yml(push, PR): yamllint for YAML syntax,jqfor JSON syntax, andopenapi spec validate(github.com/speakeasy-api/openapi — the same OpenAPI parser morphic itself depends on) for structural validity of every spec file. This was chosen over Spectral, which raised false-positive errors on this repo's OpenAPI 3.1 fixture's$id-based JSON Schema 2020-12 references.release.yml(push tomain): bundles the spec directories into a tarball and publishes it as a GitHub release tagged with the commit SHA — one release per commit onmain, no semantic versioning.$vocabularyas a bare string instead of a JSON-Schema-2020-12-compliant object) thatopenapi spec validatecaught; fixed in this copy.Test plan
openapi spec validate openapi/v3.1/petstore/spec.yaml— 0 errorsyamllint -c .yamllint.ymlagainst the seed spec — 0 errorsgo install github.com/speakeasy-api/openapi/cmd/openapi@<pseudo-version>command installs and resolves correctly (the CLI has no tagged releases, only the underlying library does)softprops/action-gh-releaseto v3 since v2 is an upstream-declared, soon-to-be-unsupported Node20 release