6 API conformance: Generating code and API definitions

 

This chapter covers

  • Handling the API server, client, and documentation conformance problem
  • Generating server code for conformance
  • Generating OpenAPI definitions for conformance
  • Generating SDKs for conformance

Imagine you’re building a public REST API. You’ve designed your OpenAPI definition and passed it through your linting and breaking change checks as described in chapters 3 and 4. You’ve built and deployed your API to your API gateway and made it live. You’ve also generated your API reference documentation from your API definition and published it to your API developer portal. Things are going well.

But now your API consumers are complaining that some details of your published API reference don’t match your live API’s behavior. For example, your API reference documentation specifies that one of the API endpoints always returns a certain field in the 200 OK response. But when consumers get a response from your API, the field is absent. There is a discrepancy between the API reference documentation and the deployed API. How do you ensure that your API server and client SDK implementation all conform to your OpenAPI definition?

6.1 The API conformance problem

6.2 Generating code from OpenAPI

6.2.1 Spring Boot from OpenAPI

6.2.2 Deploying to the gateway

6.2.3 Publishing to the developer portal

6.2.4 An update to the SOT

6.2.5 Republishing your SOT to the portal

6.2.6 Generating client SDKs

6.2.7 Advantages of generating from the SOT

6.2.8 Dealing with responses from the gateway

6.2.9 Customizing code generation

6.3 Generating OpenAPI from code

6.3.1 Generating OpenAPI with springdoc

6.3.2 Things to consider with generated definitions

Summary