Multiple APIs

[pmcelhaney]

We have multiple internal/external services that we are mocking. It would be great to run the server over multiple generated clients (with different base URLs)

Originally posted by @kaikun213 in https://github.com/pmcelhaney/counterfact/issues/823#issuecomment-2051497679

[pmcelhaney]

How would we specify multiple APIs? I'm thinking something like an OpenAPI-collection.yaml file that has a list of references to OpenAPI files and (optionally) the paths to which they map. We would pass that to the CLI in place of the OpenAPI spec. I wonder if there's already an open standard for that.

[dethell]

I poked around the OpenApi documentation and couldn't see anything for 2.0 or 3.0 that provided a mechanism for a collection of OpenAPI schemas.

Can we just have multiple instances using succeeding filenames/urls?:

npx counterfact@latest my-first-schema.json path1 my-second-schema.yml path2 ...

[pmcelhaney]

I'd rather do a config file in order to keep the CLI arguments from getting too verbose. If there's no standard we'll invent one.

[jivewise]

@pmcelhaney I could be wrong, but can't you just run counterfact multiple times on different apis now? At least when I tried it, it seemed to work. It seemingly generated the types and routes correctly. All I did was run counterfact successively with the same destination folder, and it seemed to work:

npx counterfact ./api/open-api-1.yaml ./api -g
npx counterfact ./api/open-api-2.yaml ./api -g

Adding a way to specify file wildcards would be really nice, something like npx counterfact ./api/*.yaml ./api -g

[dethell]

@pmcelhaney I could be wrong, but can't you just run counterfact multiple times on different apis now? At least when I tried it, it seemed to work. It seemingly generated the types and routes correctly. All I did was run counterfact successively with the same destination folder, and it seemed to work:

npx counterfact ./api/open-api-1.yaml ./api -g
npx counterfact ./api/open-api-2.yaml ./api -g

Adding a way to specify file wildcards would be really nice, something like npx counterfact ./api/*.yaml ./api -g

It's true you can just run it multiple times but only one at a time unless you specify alternate ports. The desire here is to have multiple specs be served under a single port at the same time.

[pmcelhaney]

Okay, you've convinced me not to do a config file. Instead we'll support @dethell's original suggestion as well as @jivewise's wildcard suggestion.

npx counterfact ./api/open-api-1.json ./api/open-api-2.json my-second-schema.yml ./api
npx counterfact ./api/*.yaml ./api

[pmcelhaney]

Adding a way to specify file wildcards would be really nice, something like npx counterfact ./api/*.yaml ./api -g

It's true you can just run it multiple times but only one at a time unless you specify alternate ports. The desire here is to have multiple specs be served under a single port at the same time.

That works for generating code (-g) but as it stands you can't point to two OpenAPI files at once while running the server. (There are a couple of reasons you'd want to do that, one is so that generated code is updated as soon as you make a change to the OpenAPI file.)

[dethell]

That works for generating code (-g) but as it stands you can't point to two OpenAPI files at once while running the server. (There are a couple of reasons you'd want to do that, one is so that generated code is updated as soon as you make a change to the OpenAPI file.)

I could see wanting it watching multiple files at once and serving them all from a single port. I don't know if basePath is required in the spec, but as mentioned way up in this discussion, if each spec has a distinct basePath that's how CF would know which file corresponds to which path.

[pmcelhaney]

Looking at this again.

Usage: counterfact [options] [openapi.yaml] [destination]

Without changing the CLI we can only put one file in the [openapi.yaml] slot. I can think of three ways to address it.

1. Allow a wildcard like "./my-specs/*.yaml" in that spot
2. Invent a new file format for a package of open-api files and put that file in the spot.
3. Add a new option like --spec <openapi.yaml> [base-path]. We can add multiple files with multiple --spec flags.

[dethell]

3. Add a new option like --spec <openapi.yaml> [base-path]. We can add multiple files with multiple --spec flags.

This last one gets my vote. Seems more explicit and clear. Using a wildcard might have broader consequences for a developer than they realize if it gobbles up more specs than intended.