swagger-cli VS bpmnlint

If you are in a situation where you have a backend and you want to expose an API and then you would eventually want a client, you would need format specs as the starting point where server and clients are generated from that one source.

At the moment, OpenAPI with YAML is the only way to go but you can't easily split the spec into separate files as you would do any program with packages, modules and what not.

There are third party tools[0] which are archived and the libraries they depend upon are up for adoption.

In that space, either you can use something like cue language 1] or something like TypeSpec which is purpose built for this so yet, this seems like a great tool although I have not tried it yet myself.

[0]. https://github.com/APIDevTools/swagger-cli

[1]. https://cuelang.org/

EDIT: formating

In order to use Redocusaurus, I needed a single spec file. Both Swagger cli and OpenApi cli offered an option to merge separate specs into one. The problem was that one of them required a "root spec file" to drive the merging and the other required extra information to resolve conflicts. My specs had neither.

We needed specialist subject matter experts in the domain to design the workflows working with behavioral science experts to author the payload text in each message. But getting a BPMN diagram into a final, computable form that passes validation checked (aka linting) requires software engineering skills and so we started out with the SME drawing an initial BPMN in Camunda’s web tool then the engineer pulls the into Camunda Modeler to do their part to make the workflow executable. The diagrams are in source control and version control is vitally important as we gathered feedback and tweaked the behavior of the system to do a better job of nudging the behavior of the humans it was interacting with.