API First Workflow: How could we have better API Docs through DevOps pipeline
I worked as the API integration engineer and Systems Architect in SAS, focusing on enabling a better design-first API development culture. I’m currently helping more than 50 internal and public APIs in SAS to onboard API First Workflow, having the company move from swagger v2 to openapi v3 smoothly and firmly. As a big fan of CICD and automation, and have worked on both the openSource side and the company side, I have a strong interest in API automation tools, building pipelines and how to have robots take boring work.
API Documentation plays an important role in improving the customer’s experience with APIs, which is always a struggle for most of the company. The way to accomplish this is to transition API development culture from “Code First” to “Design First”, here in SAS we call it “API First”. For better API designing and documentation, we have built an API First CI/CD workflow which brings many open-sourced API tools together and involves developers, product managers, documentation writers, and testers to synchronously work together to develop APIs in a “Design First” approach, the industry standard.
In the talk, we will discuss how the API-first Workflow could enable better collaboration between teams which could help in many aspects especially writing the openAPI documentation, keeping it up to date and sync with your code. We will take a deep look at one example, the Linting tool from API First workflow, which helps to make sure the API documentation follows the company standard from the start. With openSource linting tools like Spectral, it’s easy for teams to define their own linting rules which includes company standards. When your API specifications go through the linter in the CI/CD pipeline, the linter will throw errors and warnings as you write your spec. This will help ensure your specification is following proper guidelines and that’s all automatic.