Open API first development

Unknown

I've been thinking recently about tweaking our dev workflow to starting API development with the Open API spec as the first step to coding endpoints. Currently we develop endpoints and then have the Open API documentation automatically delivered via a plugin. I spoke with @Ryan quite a bit about this, but wanted to loop others in to see what they thought.

Here is an overview of the upsides/downsides of a system with the intent of starting a discussion about it.

Downsides of the current system

1. The Open API spec is not currently correct. It works for generating the Swagger UI docs, but other tooling may fail. Moreover, it will be quite difficult to ensure that the spec is always correct.
2. We can't use all the features of Open API. There are features such as defining all return types and webhooks that may be interesting to use in our spec.
3. The current Open API generation is bound to cause security concerns as it calls every endpoint. If we make a misstep then it could open our code up to hackers.

Upsides of writing the Open API first

1. We could write the open API spec first so that the entire team would know what the API looks like before the endpoint development starts. This should help remove bottlenecks and allow us to separate tasks between different devs more easily.
2. We'd more easily be able to validate the API against Open API. We could even do this in our CI to ensure the spec always conforms.
3. The API spec becomes source code so we always know where the API stands.
4. The spec being source code will make things easier for our docs site that uses a static doc.
5. We could add more extensive documentation to the doc with examples.
6. We could use more models in the spec or share them across resources more easily.
7. We could use the Open API spec to generate client-side typescript definitions. Right now it all has to be done manually.

Risks

1. We already have a decent dev workflow. We would still continue this today, but with an additional Open API step. Longer term we would have to create some code so that the server could also use the Open API spec.
2. The swagger-ui plugin will need refactoring.
3. We will have to develop more tooling in general to support typescript, deploy generation, etc.
4. Open API and JSON schema are slightly different. We will have to go in one direction to make garden-schema more of an Open API schema parser which could limit its utility. This also requires more work.
5. Currently, our schema can validate a model using an existing sparse schema which removes some boilerplate. Open API doesn't have this so we would have to spec out separate POST/PATCH schemas that are largely identical except for the required property.
6. Devs are going to have to learn Open API. Oh my!

Architecture

I'm suggesting that we simplify how we code the spec so that we have our docs mostly in one place.

1. This would be an Open API 3.0 spec. We would be leaving Open API 2.0 behind.
2. We maintain two open API specs: a) all of our open source endpoints will be maintained in the vanilla repo, and b) all of our closed source endpoints will be maintained in the internal repo.
3. We will make use of a custom x-addon attribute on the schema to designate that a particular addon owns an endpoint, property, etc. We should use this for everything except the dashboard addon.
4. Closed source addons that add fields to an open source endpoint can just be added in the vanilla repo.
5. The in-dashboard docs will be filtered based on the x-addon attributes and what is enabled before serving. We can also run the spec through translation during this process at some point in the future.
6. We will need to reconstitute the entire Open API spec from the open/closed source upon deploy.

Possible Tools

There are some possible tools we could develop to help us use the Open API specs, either separate command line tools or classes we could use in our app.

1. Generate a typescript client from the Open API spec.
2. There are other command line tools to generate API clients for a variety of languages.
3. The dispatcher could be modified to use the spec to route instead of our current automagical wiring. This would allow for more flexible routes, but would require augmenting the spec with route information as another x- attribute.
4. If the dispatcher is used to route it could validate the endpoint's schema before calling the endpoint.
5. Endpoints themselves could load their specific sliver of the spec to validate rather than constructing their own schemas.

There are a lot of tools that take advantage of Open API. We would be well served researching them to see what may benefit our development workflow.

Unknown

After spending much of Friday night improving our swagger validation I'm adding a few more points.

1. It is too onerous for devs to code endpoints that both work as an endpoint and generate proper documentation. I found several understandable typos as well as some schemas that were properly coded in terms of use, but impossible to make work properly for documentation.
2. We don't currently have a process to ensure the docs are correct so they probably never will be until Open API validation is part of our build process.