Create dev build infrastructure

[handrews]

I had a check fail on #4188 on v3.2-dev and realized that there's no way to build without copying things over to the publish location (and even then something went weird when it was trying to build the old versions b/c the dev branches aren't set up for that).

We should be able to build just src/oas.md for testing purposes on dev and all branches derived from dev.

This change should go into dev and be merged/cherry-picked out from there.

If Arazzo and Overlay are going to use the same system, this might also be a good time to start building a shared system instead of continuing to patch things in triplicate.

• Build src/oas.md
• Build schemas from src
  • dev: schemas live in src folder #4361
• Test schemas in src upon push
• Validate & lint src/oas.md upon push
• Format src/oas.md
  • dev: format src/oas.md #4336

[ralfhandl]

@handrews How luxurious do you want it to be?

The simplest solution would be to add a script npm run build-src that creates a static oas.html next to the oas.md (or anywhere you like) and add that file to .gitignore.

A nicer experience would be to start a tiny express server via npm run serve-src that dynamically produces an ephemeral oas.html on every change of oas.md and tells the browser to auto-refresh. That way you could have a browser window next to your editor window, type in one and live-check the other.

I have copy templates for both approaches lying around 😎

[handrews]

@ralfhandl I'm perfectly happy with the simple version (and would be more likely to use it TBH because all of my dev tools tend to be the lowest-tech that works for me). But if you want to do the more complicated thing I'm not going to stop you.

Although... express seems like a bit dependency to add, and I'd kind-of like to be able to just build and look at the HTML without running a server. I guess just make sure I don't have to understand express at all to use the build system.

[ralfhandl]

I'm perfectly happy with the simple version

@handrews Please check

• dev: build HTML from src/oas.md #4254

[ralfhandl]

@handrews regarding

• Build schemas from src

What would you expect this to do?

The work-in-progress schema in src/schemas/validation/schema.yaml is already validated by the schema tests, and the build step just converts the YAML files into JSON, renames them, and adjusts the corresponding $references.

[handrews]

@ralfhandl I don't even remember writing that! I think I did mean "build the JSON from the YAML and update the ids and references in both", with the intention being to load the built schemas and make sure that the references all line up.

I mean, ideally a build would produce an entire updated local spec.openapis.org site that you could browse, which would be helpful in the future if we start having the specs cross-reference each other. But that's rather more ambitious. Just ensuring that the build JSON with the adjusted ids and refs load properly and validate against their metaschemas would be a good thing.