Yantian You - API First Workflow: How could we have better API Docs through DevOps pipeline

Code first approach

Simplified workflow

1. Backend developers write the code,
2. Hand the code over to the Testers,
3. The Documentation team (Developers and Technical writers) writes the docs,
4. The Review team reviews it.

The issue

• Takes too much time for the reviewers
• Very expensive to change
• Teams don’t have much time to change the code nor the documentation
• Not efficient

API First approach

Parallel and synchronous team work

The Developer, Tester, Documentation, and Delivery teams work together and synchronously under the guidance of a Product Manager, who knows exactly what the customer needs.

Product Managers:

• Decision makers
• Drivers
• Link the teams together
• Give feedback from the customers

The work starts with writing the API specification: the development bends before the design.

API First roadmap with OpenAPI 3.0 Specification

OpenAPI 3.0 Specification is human-friendly, and machine-readable

• Increases efficiency: teams can work in parallel using a flexible architecture.
• Opens up opportunities for automation (CI/CD): automated testing, documentation, and some degree of code-generation.
• Increases the usability for end-users: the documentation can help the customers to understand the API.

API First workflow

The workflow happens through a centrally managed tooling package, architected for easy switching to new tools.

1. Development cycle

• Manual work:

  • writing the API specification,
  • sending the pull requests,
  • doing the team review.

• Automatic work:

  • linting (with open-source tools like Spectral) – the linter can run locally,
  • generating and using mock-servers (with open-source tools like Prism or APIsprout) – they can run locally and remotely,
  • merging to the repository after the Review team approved.

Result: API specification

Design workshop

To get an API specification at the very beginning

• Brainstorming, idea-sharing between the product manager, the customer, other stakeholders, testers, and developers
• The result is the API specification
• Very manual work, but open-source tools can help generating and editing the API specification

2. Continuous integration layer

• Manual work: none

• Automatic work:

  • Mock server started
  • Client code generated
  • Documentation generated
  • Server code generated

3. Development cycle continues

• Manual work:
  1. Testers/Pre-sales: don’t have to wait until the real logic comes out – they can use the mock server and the generated client code
  2. Technical writers: can edit the generated documentation – they can provide early feedback for the developers
  3. Developers: write the code, add the logic
  4. Testers: can test the code and the functionality
  5. Review team: does a final review after the code passed the tests
      
• Automatic work:
  • Code committing
  • Contract testing to check whether documentation matches with the code
  • Publishing the API
     
• Result: Published API