jmaeso / codegen-exploration

This repository hosts some simple code since the focus will be in the details and the processes

codegen-exploration

This repository hosts some simple code since the focus will be in the details and the processes

Hypothesis / Goal

Be able to build APIs with a schema-first approach, which would allow us to:

• Autogenerate most of the code (at least request, params and response types) in the "HTTP layer".
• Documentation always up-to-date by definition.
• Allow the service to serve its own documentation to facilitate integrations.
• From a single schema file.
• Eventually generate client code for that API.

Process of the exploration

1. Defined docs/openapi.yaml (using version 3.0.2).
2. Added make openapi-gen to generate go models for the API (using openapi 3.0.2).
3. Updated docs/openapi.yaml (now version 3.1.0).
4. Added make openapi-lint to validate new version is valid.
5. Added make jsonschema-gen (using https://github.com/atombender/go-jsonschema).

Notes

• Adding $schema: https://json-schema.org/draft/2020-12/schema to the openapi.yaml (3.1.0) file avoids the gojsonschema generator to fail, but generates an empty go file.
• Interesting feature for gojsonschema: Be able to provide a custom type (and package) for types with format. It would be nice to have UUID or ISO 3166 validations...
  • Idea: Support x-go-customType: {package.type} for properties so a custom type can be used for them. Example:

      id:
          x-go-customType: github.com/google/uuid.UUID
          description: Unique identifier of the user.
          type: string
          format: uuid
          example: e22896bb-de9c-47d1-b5ae-005c31d49a6f

  • Update: Maybe it would be more scalable to use the validator package
• The other interesting go code generator library (https://github.com/a-h/generate) does not support yaml as an input.