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.

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

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.