Missing features

[armorjones]

Context:
We've engineered a similar Swaggerhub CLI tool internally to our company and have included several major features which are not seen in the official SmartBear release. List all APIs in given org, view a spec locally (we use ReDoc), and list/view versions of a spec to name some of the major features. Other features include saving the spec as either json or yaml and by a given filename to a specified location.

The ask:
We'd be happy to sunset our tool in favor of this release for various reasons. But we'd like to see listing specs, listing and viewing versions.

swaggerhub api:list OWNER
swaggerhub api:versions API_NAME
swaggerhub api:get OWNER/API_NAME/[VERSION] --output <output_filename>.<json|yml|yaml>
swaggerhub api:view OWNER/API_NAME/[VERSION]

• In the case of swaggerhub api:view we use the redoc-cli tool to generate a static html file in tmp and open that file.
• In the case of swaggerhub api:get --output we could get creative on implementation, right now we let the user to define directory, version, format and filename, --dir, --version, --format and --filename respectively. But I could see using just --output to do something like --output /path/to/file.yaml --version 1.3.5

When you begin accepting PRs I'd be happy to contribute some of these ideas for your review. Unless of course you'd like to tackle some/all of these? :)

[smizell]

Hi @armorjones 👋 Thanks for this—it's really cool to hear. As you saw, we're in our first release and not quite ready to accept PRs. Once we get to a stable point, we'll circle back to you here to chat about how you can contribute. We're excited to start taking outside help.

As a bit of background, we've been focusing on the use case of using this CLI in a build pipeline. We're wanting to help people build automation around SwaggerHub, and the CLI can help. Some of these commands you've listed are focused more on exploring what's in SwaggerHub. These are in our plans, but they're a bit further down since it's not a thing one would do during automation—though I'm sure there are cases!

I do have a couple of questions for you if you have time.

On the output of commands

Regarding the --output idea, api:get will return YAML by default and JSON with the --json argument. You can then redirect the output to the file of your choice.

swaggerhub api:get owner/api/version > myfile.yml

Would this work for you? Does --output solve a different use case for you?

CLI for local development

Am I right in assuming you're using the CLI for local development? Would you be able to share any details about how you or other developers are using it for that purpose? It would be great to hear because it can help us plan for thinking about local development use cases.

Thanks again!

[armorjones]

Hi @smizell - Thanks for the quick response! And yes, it's all making sense now, first major release focused on CI/CD. Being that we are focused on "Spec First Design" standards, it didn't cross my mind to use this as a means of managing specification in the build/deployment pipeline. Makes sense!

re: Output -- Yes, piping out to file will work just fine! And honestly is probably a more right approach. So your example will be suitable and more readable. :)

re: Local development -- Yes and no. I built the tool for both engineers and product. Engineers, so they can write automation in there Gradle tasks or Node scripts, things like fetching latest spec and writing it to root enabling apps to validate on spec at run time. And product, so they can quickly view and compare specs and respective versions. We use ReDoc as the html output when running swaggerhub api:view api as it is closer in design to our final outward facing API specifications/documentation, and it rings more 'readable' for them.

As mentioned above, as I'm sure many other teams do, we tightly couple our specifications with API request validation. It's important for us to have automation tools (such as this CLI tool) embedded in our SDLC at all phases to ensure we are delivering exactly what we set out to deliver. -- It never occurred to me to write a task/script that pulls the spec at build time, some teams have been using tasks to push an autogenerated spec (think Spring), which I've been pushing to move away from as it is the antithesis of "spec first design", imho.

tldr; Great work! Yes, api:get will work out just fine. And will likely use it as part of local and pipeline builds process.

Sorry, if this appears as a brain dump, I'm multi-tasking atm.

[smizell]

As mentioned above, as I'm sure many other teams do, we tightly couple our specifications with API request validation. It's important for us to have automation tools (such as this CLI tool) embedded in our SDLC at all phases to ensure we are delivering exactly what we set out to deliver.

This is an important comment. To do a spec first approach well, you have to do the things you're doing. It's especially important to move people from an approach of generating Are you able to share what you're using for request validation? Do you do this during testing or in production? No problems if you can't release that information :)

We're adding support for checking the validation status of a version in SwaggerHub, which will enable people to use our Standardization during their build process. If you use any kind of standardization/style guide for this purpose, we'd love to hear about it!

[miqui]

hi @smizell - while you are at it, please for this comment swaggerhub api:validate enable json output... we use jq heavily in our pipelines... thanks.

[jeremyfiel]

I would like to see a separate custom rule config file that can be run from the cli. hopefully formatted close to the others so it can be easily migrated

allow json-path plus and custom functions to be written a la the other linters out there.

the standardization (at least on-prem) leaves a lot to be desired.