How to keep OpenAPI specification up-to-date and compliant without using code generators?

Question

In our company, there is no standard for how to document APIs. Missing API documentation slows down the development process.

Therefore, we want to introduce OpenAPI.

We want to use code generators to ensure that the OpenAPI specification is up-to-date and to ensure that the services are compliant with the OpenAPI specification that they publish.

However, sometimes code generators generate code that is not up to agreed coding standards, sometimes code generators are out-of-date, or sometimes they may not be available.

How could we ensure that OpenAPI documentation is up-to-date and compliant when code generators are noted used?

Answer 1

Coding standards exist to help humans read the code. It is easier to read and maintain code, and therefore reduce bugs, if you have a well-defined and consistent style and standards. However, humans should, as a general rule, not be regularly reading generated code. Any standards or conventions should be applied to the input to code generation tools, not the output, since the input is what humans will need to read and maintain.

Instead of inventing a problem of enforcing your code style, conventions, and standards on generated code, focus on the other problems of not having generators for things that should be generated. By making sure you can generate your documentation, ideally as part of your build processes, you can reduce or eliminate the problem of the lack of API documentation slowing down the development process.

Answer 2

Generate the OpenAPI Specification

Several languages having tooling that supports both:

1. Generating code from an Open API Spec.
2. Generating an Open API spec from code.

Note: Typically you would choose a direction - either generate the code or generate the Open API spec - do not try to do both in one project.

How could we ensure that OpenAPI documentation is up-to-date and compliant when code generators are noted used?

If you don't want to generate any code, you can look into a tool set for your language that will generate the Open API spec for you.

Client Stubs

Generating the OpenAPI spec is only a partial solution, as most of the existing tools are designed so that you can:

• Write the server implementation.
  • Include comments or annotations (depending on the language) to define the OpenAPI spec in the code.
• Generate the OpenAPI spec from the server code.
• Generate client stubs (from the OpenAPI spec).

If you insist on no code generation you could "jump through hoops", for example by creating a seperate package that contains the "transport model" (set of classes that are serialized/deserialized - typically to JSON). So that you can use the same package/model in both the server and client code.

However I don't see a problem with generating client stubs. Since you typically don't need to edit any of the generated code - it might be necessary for someone to open the generated code to get a feel for what the code generator is generating - but once they understand how it works, it is unlikely they will need to look at the generated code again.

Templated Server Side Implementations

sometimes code generators generate code that is not up to agreed coding standards,

This is only really a problem if you intent to edit the code after it has been generated and typically this only happens when you use a code generator to generate the empty methods for the server implementation.

The way I have solved this problem is to have the code generator generate interfaces. The classes that implement the interfaces are then hand coded - any change to the generated interface causes a compile time error. I typically use an IoC framework to inject the dependencies, but you could just establish a naming convention for your implementation classes.

Unfortunately its unlikely there will be a code generator that exactly meets your needs for this approach, so you will either need to:

• Extend the existing OpenAPI generators - there is good documentation on how to do that.
• (or) Roll your own code generator.

sometimes code generators are out-of-date, or sometimes they may not be available.

Any code generator you maintain will be completely up to date and contain all the features you need....

Good Documenation

Missing API documentation slows down the development process.

When open API is tied to the code (code/spec generation) - it is very good at enumerating structures / ensuring typo's don't creep in.

But it is not a substitute for good documentation. So many times I see a field in OpenAPI documented as:

String flibwibble - The current Flibwibble.

Nowhere in the OpenAPI documentation does it explain what a Flibwibble is... To put it another way you should probably also have good API documentation in addition to the OpenAPI spec.