Creating a new resource, docs are not clear

[mrded]

I’m trying to create a new resource using vervet and found docs a bit confusing.

https://github.com/snyk/vervet/blob/main/README.md?plain=1#L156

It’s not clear from the command which is a command and which is a value. Here I don’t understand what my-api stays for, and I kinda guess what thing is, as below it's shown in the resources tree 😕

The CLI help can also be a bit more informative. I'd like to see an example of creating a new resource.

[cmars]

Interesting. You know, I'm not a fan of the vervet version subcommand because as soon as I landed it, I felt like version is probably something you'd expect to tell you the version of vervet you're running.

[cmars]

Trying to find a balance between concise and intuitive. Some ideas:

Maybe a resource subcommand is better?

vervet resource list --all
vervet resource list --api petstore
vervet resource show --api petstore --name pets
vervet resource new --api petstore

@jcsackett added prompting when a needed parameter is missing, so we could combine with that,

vervet resource new  # prompts for the API and resource

What do you think of these new commands, and deprecating the version one (to sunset with the next major release)?

[cmars]

We might even draw a distinction between resources (which are about the collection of version releases) and the endpoints (path + operation within each resource version) so commands like:

vervet endpoint list --api petstore --resource pets
# Columns are: Version, Path, Method, Operation ID
2022-02-03  GET  /pets          listPets
2022-02-03  GET  /pets/{id}   getPet

[cmars]

Or maybe it's vervet resource new-version... gotta think on it.

[cmars]

Scaffolding OpenAPI has moved to https://github.com/snyk/sweater-comb (sweater-comb workflow ...)