jtd-codegen 0.1.4

Generate code from JSON Typedef schemas
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125

# `jtd-codegen` + Golang

This README contains details of how to use `jtd-codegen` in conjunction with
Golang.

* For documentation on `jtd-codegen` in general, see [the top-level
  `jtd-codegen` README](../../..).

* For a more guided explanation of how you can integrate Go code generated by
  `jtd-codegen` into your codebase, see ["Generating Golang from JSON Typedef
  Schemas"][jtd-go-codegen] in the JSON Typedef docs. This README will focus on
  specific technical documentation.

## Configuration Options

The Golang code generator has only one option:

* `--go-out` specifies the output directory that `jtd-codegen` should generate
  Golang into. If this flag is omitted, then `jtd-codegen` will assume you don't
  want to generate Golang.

  The `--go-out` flag also controls the name of the Golang package that
  `jtd-codegen` will generate. The last segment of the directory name will be
  used as the package name. For example, if you pass `--go-out=foo/bar/baz`,
  then `jtd-codegen` will emit code with a declaration of `package baz`.

## Notes on Generated Code

### Cleanliness of generated code

`jtd-codegen` will not always generate "pretty" code, but it will always
generate correct code. It's recommended that you run `go fmt` on the generated
code.

### Generating GoDoc-style comments

`jtd-codegen` supports GoDoc-style comments in generated Go code. To have
`jtd-codegen` generate a documentation comment for a particular `type`, `const`,
`struct`, or `struct` element, use a `description` property inside the
`metadata` of a schema.

For example, if you have a schema like this in a file called `user.jtd.json`:

```json
{
  "metadata": {
    "description": "This is a user."
  },
  "properties": {
    "name": {
      "metadata": {
        "description": "The user's name"
      },
      "type": "string"
    },
    "favoriteNumbers": {
      "metadata": {
        "description": "The user's favorite numbers"
      },
      "elements": {
        "type": "float64"
      }
    }
  }
}
```

Then `jtd-codegen` will generate something like:

```go
// This is a user.
type User struct {
  // The user's name
  Name string `json:"name"`
  // The user's favorite numbers
  FavoriteNumbers []float64 `json:"favoriteNumbers"`
}
```

### Inferred type names

`jtd-codegen` infers the name of the "root" type it generates from the name of
the file you generate code from. For example, if you generate code from a file
called `user.jtd.json`, the generated top-level Go type will be called `User`.

`jtd-codegen` uses the names of definitions to determine the name of types
described in a JSON Typedef definition. For example, if you have a schema like
this in a file called `example.jtd.json`:

```json
{
  "definitions": {
    "thing": {
      "properties": {
        "foo": { "type": "string" },
        "bar": { "type": "string" }
      }
    }
  },
  "properties": {
    "thing1": { "ref": "thing" },
    "thing2": { "ref": "thing" }
  }
}
```

Then `jtd-codegen` will generate something like:

```go
type Thing struct {
  Foo string `json:"foo"`
  Bar string `json:"bar"`
}

type Example struct {
  Thing1 Thing `json:"thing1"`
  Thing2 Thing `json:"thing2"`
}
```

You can use this to your advantage. If there's a particular sub-component of a
schema that you'd like `jtd-codegen` to generate a specific name for, put that
sub-component in a definition with the name you want.

[jtd-go-codegen]: https://jsontypedef.com/docs/golang/code-generation