Nola Di Mare Sullivan is the head of developer relations at Speakeasy. He works there to ensure that every organization can give developers a first-class experience using their APIs. In this article, he discusses Code Generation.
Typically, most companies’ journey starts with maintaining an OpenAPI spec because it’s been mandated by the leadership team. The team is not deriving value from it, so they are not very keen to do it. Then, at some point, people will realize that if we’re maintaining this thing, we might as well make it valuable. And usually, the first application of the OpenAPI spec is for keeping documentation up to date. The OpenAPI spec is a reference of your API, which can be used to create the classic three-panel documentation site you’ve probably seen when trying to get started using an API. So that’s the second phase, and to be honest, that’s where many companies are probably today. There’s a further stage of sophistication, which is where people should be trying to get to, and it’s where the most advanced engineering organizations are today, which is using your OpenApi spec to build libraries that power internal and external development.
Some organizations use OpenApi to create client libraries and server stubs. This allows people to access your API using the language they’re most familiar with and spares them from writing code that makes integrating with API difficult. This will help you convert more users into paying users, give them a better overall experience, and help maximize usage in the long term.
Consider the following points to achieve a higher level of developer experience.
- We can’t use our spec for code generation because we don’t have the right staffing level. And we haven’t built a sophisticated enough governance workflow. But, if you wait for everything to be perfect before you start, it will not happen. If you wait for value, no one will want to use the API; if no one will use the API, it will not generate value. If you can generate libraries using OpenApi spec, the developers within your organization can use those libraries, and it improves their lives. Now, you’ve created an incentive for them to ensure that those specs stay current and have the latest information. Starting small makes it easier to explain to people that they can work towards a better future.
- Pay attention to operation IDs. Operation IDs are unique values that get added to each operation or method in the spec. If you are going to use code generation, ensure that it is descriptive and humanly readable. Ensure you follow a consistent pattern. Stick to simple alphanumerics and separators, e.g., a dash or underscore.
- Reuse components and schemas wherever possible. Component schemas will become shared types, making maintenance easier and improving readability.
- Use tags to group your resources. Have a tag for each resource that is exposed by your API. Think carefully before you associate a method with multiple tags. Ensure that it does not conflict with your docsite.
- People will encounter errors when using an API, so find ways to track them. Define component schemas for error responses. The more you enumerate, the better.
- Overcome spec fragility with overlays. People are unsure about the outcome if they edit a spec because they are unsure of the workflows and their requirements. This is more common in larger and older organizations. So, to modify a spec without breaking existing workflows, you can use overlays. An overlay is, a file that lives alongside your spec. It just specifies a list of edits you want to make to the OpenApi specification. You save this list of manipulations that are going to be made to your canonical spec. The overlay file can contain the edits you would have wanted to make to your spec to optimize it for the codegeneration. So, you are changing your spec without needing to change the spec that the existing workflows are using.
To conclude, you can use multiple tools. Speakeasy is one such tool.
