Skip to content

Commit c8c0801

Browse files
pkedypkedy
committed
Add generator documentation
1 parent 9aa5e72 commit c8c0801

19 files changed

+397
-25
lines changed

‎docs/tutorial-extras/_category_.json renamed to ‎docs/customization/_category_.json

+1-1
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
{
2-
"label": "Tutorial - Extras",
2+
"label": "Customization",
33
"position": 4,
44
"link": {
55
"type": "generated-index"

‎docs/tutorial-extras/custom-generators.md renamed to ‎docs/customization/custom-generators.md

File renamed without changes.

‎docs/customization/project-templates.md

+13
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
---
2+
sidebar_position: 2
3+
---
4+
5+
# Project Templates
6+
7+
```cli
8+
apex new @apexlang/codegen/go greeter \
9+
module=github.com/apexlang/greeter \
10+
package=greeter
11+
```
12+
13+
TODO

‎docs/generators/go.md

+186-2
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,191 @@
11
---
2-
sidebar_position: 1
2+
title: Go
33
---
44

55
# Go
66

7-
TODO
7+
Generate code for the [Go programming language](https://go.dev).
8+
9+
## InterfacesVisitor
10+
11+
<p>
12+
<span className="badgeDarkBlue">Core logic</span>
13+
<a href="https://github.com/apexlang/codegen/blob/main/src/go/interfaces_visitor.ts" target="_blank" rel="noopener noreferrer">Source code <svg width="13.5" height="13.5" aria-hidden="true" viewBox="0 0 24 24" class="iconExternalLink_node_modules-@docusaurus-theme-classic-lib-theme-Icon-ExternalLink-styles-module"><path fill="currentColor" d="M21 13v10h-21v-19h12v2h-10v15h17v-8h2zm3-12h-10.988l4.035 4-6.977 7.07 2.828 2.828 6.977-7.07 4.125 4.172v-11z"></path></svg></a>
14+
</p>
15+
16+
Generates interfaces annotated with `@service` and `@dependency` along with structs and enums. These interfaces act as the main contract between the application's core logic and external dependencies such as other APIs or datasources.
17+
18+
#### Example
19+
20+
```yaml
21+
config:
22+
package: myapp
23+
generates:
24+
pkg/myapp/interfaces.go:
25+
module: '@apexlang/codegen/go'
26+
visitorClass: InterfacesVisitor
27+
config:
28+
# Used by ImportsVisitor, AliasVisitor
29+
aliases:
30+
UUID:
31+
type: uuid.UUID
32+
import: github.com/google/uuid
33+
```
34+
35+
#### Configuration
36+
37+
| Field | Description |
38+
| ----------------------- | --------------------------------------------- |
39+
| `package` (common) | The name of the Go package |
40+
| `aliases` | Maps Apex aliases to specific Go types |
41+
42+
#### Callbacks
43+
44+
| Name | Description |
45+
| ----------------------- | --------------------------------------------- |
46+
| `StructTags` | Write additional struct tags to structs |
47+
| `UnionStructTags` | Write additional struct tags to union structs |
48+
49+
#### Overridable Nested Visitors
50+
51+
| Class | Description | Override function(s) |
52+
| ----------------------- | --------------------------------------------- |-------------------|
53+
| [`ImportsVisitor`](https://github.com/apexlang/codegen/blob/main/src/go/imports_visitor.ts) | Writes the imports required by the `.go` file. | `importsVisitor` |
54+
| [`InterfaceVisitor`](https://github.com/apexlang/codegen/blob/main/src/go/interface_visitor.ts) | Writes an Go interface for all `@service` and `@dependency` Apex interfaces. | `serviceVisitor`, `dependencyVisitor` |
55+
| [`StructVisitor `](https://github.com/apexlang/codegen/blob/main/src/go/struct_visitor.ts) | Writes a simple Go struct for Apex types. | `structVisitor` |
56+
| [`EnumVisitor`](https://github.com/apexlang/codegen/blob/main/src/go/enum_visitor.ts) | Writes an enum using `const` and various `func`s. | `enumVisitor` |
57+
| [`UnionVisitor`](https://github.com/apexlang/codegen/blob/main/src/go/union_visitor.ts) | Writes an Apex union as a Go struct with optional fields for each declared type. | `unionVisitor` |
58+
| [`AliasVisitor`](https://github.com/apexlang/codegen/blob/main/src/go/alias_visitor.ts) | Writes an alias type to map to an internal or third-party Go type (e.g. UUID) | `aliasVisitor` |
59+
60+
## MainVisitor
61+
62+
<p>
63+
<span className="badgeDarkBlue">Project creation</span>
64+
<a href="https://github.com/apexlang/codegen/blob/main/src/go/main_visitor.ts" target="_blank" rel="noopener noreferrer">Source code <svg width="13.5" height="13.5" aria-hidden="true" viewBox="0 0 24 24" class="iconExternalLink_node_modules-@docusaurus-theme-classic-lib-theme-Icon-ExternalLink-styles-module"><path fill="currentColor" d="M21 13v10h-21v-19h12v2h-10v15h17v-8h2zm3-12h-10.988l4.035 4-6.977 7.07 2.828 2.828 6.977-7.07 4.125 4.172v-11z"></path></svg></a>
65+
</p>
66+
67+
This visitor creates the initial entry point (`main.go`) for your application and stubs out creation of services and dependencies and can server HTTP and/or gRPC.
68+
69+
#### Example
70+
71+
```yaml
72+
generates:
73+
cmd/main.go:
74+
ifNotExists: true
75+
module: '@apexlang/codegen/go'
76+
visitorClass: MainVisitor
77+
config:
78+
package: myapp
79+
http:
80+
enabled: true
81+
defaultAddress: ":3000"
82+
environmentKey: HTTP_ADDRESS
83+
grpc:
84+
enabled: true
85+
defaultAddress: ":4000"
86+
environmentKey: GRPC_ADDRESS
87+
```
88+
89+
#### Configuration
90+
91+
| Field | Description |
92+
| ----------------------- | --------------------------------------------- |
93+
| `package` (common) | The name of the Go package |
94+
| `module` (common) | The application's Go module name |
95+
| `http.enabled` | (default `true`) Flag to generate code to listen for HTTP |
96+
| `http.defaultAddress` | (default `:3000`) The default listening address for HTTP |
97+
| `http.environmentKey` | (default `HTTP_ADDRESS`) The environment variable to set the listening address for HTTP |
98+
| `grpc.enabled` | (default `true`) Flag to generate code to listen for gRPC |
99+
| `grpc.defaultAddress` | (default `:4000`) The default listening address for gRPC |
100+
| `grpc.environmentKey` | (default `GRPC_ADDRESS`) The environment variable to set the listening address for gRPC |
101+
102+
## ScaffoldVisitor
103+
104+
<p>
105+
<span className="badgeDarkBlue">Project creation</span>
106+
<a href="https://github.com/apexlang/codegen/blob/main/src/go/scaffold_visitor.ts" target="_blank" rel="noopener noreferrer">Source code <svg width="13.5" height="13.5" aria-hidden="true" viewBox="0 0 24 24" class="iconExternalLink_node_modules-@docusaurus-theme-classic-lib-theme-Icon-ExternalLink-styles-module"><path fill="currentColor" d="M21 13v10h-21v-19h12v2h-10v15h17v-8h2zm3-12h-10.988l4.035 4-6.977 7.07 2.828 2.828 6.977-7.07 4.125 4.172v-11z"></path></svg></a>
107+
</p>
108+
109+
This visitor will stub out an implementation for the configured interfaces leaving the developer to fill in the logic.
110+
111+
#### Example
112+
113+
```yaml
114+
generates:
115+
pkg/myapp/services.go:
116+
ifNotExists: true
117+
module: '@apexlang/codegen/go'
118+
visitorClass: ScaffoldVisitor
119+
config:
120+
types:
121+
- service # any interfaces with @service
122+
pkg/myapp/repositories.go:
123+
ifNotExists: true
124+
module: '@apexlang/codegen/go'
125+
visitorClass: ScaffoldVisitor
126+
config:
127+
names:
128+
- Repository # a data store interface
129+
```
130+
131+
#### Configuration
132+
133+
| Field | Description |
134+
| ----------------------- | --------------------------------------------- |
135+
| `package` (common) | The name of the Go package |
136+
| `names` | The names of specific interfaces to generate |
137+
| `types` | The types interfaces to generate based on annotations (i.e. `@service`) |
138+
139+
## FiberVisitor
140+
141+
<p>
142+
<span className="badgeDarkBlue">Transport layer</span>
143+
<a href="https://github.com/apexlang/codegen/blob/main/src/go/fiber_visitor.ts" target="_blank" rel="noopener noreferrer">Source code <svg width="13.5" height="13.5" aria-hidden="true" viewBox="0 0 24 24" class="iconExternalLink_node_modules-@docusaurus-theme-classic-lib-theme-Icon-ExternalLink-styles-module"><path fill="currentColor" d="M21 13v10h-21v-19h12v2h-10v15h17v-8h2zm3-12h-10.988l4.035 4-6.977 7.07 2.828 2.828 6.977-7.07 4.125 4.172v-11z"></path></svg></a>
144+
</p>
145+
146+
This visitor is used to create a REST/HTTP wrapper around `@service` interfaces using the [Fiber](https://gofiber.io) package. Since Fiber is built on top of [Fasthttp](https://github.com/valyala/fasthttp), your apps will be more tuned for high performance.
147+
148+
#### Example
149+
150+
```yaml
151+
generates:
152+
pkg/myapp/interfaces.go:
153+
module: '@apexlang/codegen/go'
154+
visitorClass: FiberVisitor
155+
config:
156+
package: myapp
157+
```
158+
159+
#### Configuration
160+
161+
| Field | Description |
162+
| ----------------------- | --------------------------------------------- |
163+
| `package` (common) | The name of the Go package |
164+
165+
## GRPCVisitor
166+
167+
<p>
168+
<span className="badgeDarkBlue">Transport layer</span>
169+
<a href="https://github.com/apexlang/codegen/blob/main/src/go/grpc_visitor.ts" target="_blank" rel="noopener noreferrer">Source code <svg width="13.5" height="13.5" aria-hidden="true" viewBox="0 0 24 24" class="iconExternalLink_node_modules-@docusaurus-theme-classic-lib-theme-Icon-ExternalLink-styles-module"><path fill="currentColor" d="M21 13v10h-21v-19h12v2h-10v15h17v-8h2zm3-12h-10.988l4.035 4-6.977 7.07 2.828 2.828 6.977-7.07 4.125 4.172v-11z"></path></svg></a>
170+
</p>
171+
172+
This visitor is used to create a gRPC wrapper around `@service` interfaces using [protoc-gen-go](https://grpc.io/docs/languages/go/quickstart/). This should be used in conjunction with [ProtoVisitor](proto#protovisitor).
173+
174+
#### Example
175+
176+
```yaml
177+
generates:
178+
pkg/myapp/interfaces.go:
179+
module: '@apexlang/codegen/go'
180+
visitorClass: GRPCVisitor
181+
config:
182+
package: myapp
183+
protoPackage: github.com/myorg/myapp/proto
184+
```
185+
186+
#### Configuration
187+
188+
| Field | Description |
189+
| ----------------------- | --------------------------------------------- |
190+
| `package` (common) | The name of the Go package |
191+
| `protoPackage` | The package name of the gRPC generated code |

‎docs/generators/openapi.md

+29
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,29 @@
1+
---
2+
title: OpenAPI
3+
---
4+
5+
# OpenAPI Specification
6+
7+
Generate [Swagger/OpenAPI specification](https://swagger.io/specification/) files using Apex.
8+
9+
## OpenAPIV3Visitor
10+
11+
<p>
12+
<span className="badgeDarkBlue">Transport layer</span>
13+
<a href="https://github.com/apexlang/codegen/blob/main/src/openapiv3/openapiv3.ts" target="_blank" rel="noopener noreferrer">Source code <svg width="13.5" height="13.5" aria-hidden="true" viewBox="0 0 24 24" class="iconExternalLink_node_modules-@docusaurus-theme-classic-lib-theme-Icon-ExternalLink-styles-module"><path fill="currentColor" d="M21 13v10h-21v-19h12v2h-10v15h17v-8h2zm3-12h-10.988l4.035 4-6.977 7.07 2.828 2.828 6.977-7.07 4.125 4.172v-11z"></path></svg></a>
14+
</p>
15+
16+
This visitor creates a valid [Swagger/OpenAPI v3 specification](https://swagger.io/specification/) for all `@service` interfaces using [protoc-gen-go](https://grpc.io/docs/languages/go/quickstart/). This should be used in conjunction with a language specific wrapper generator (for example, [FiberVisitor for Go](go#fibervisitor)) to generate the boilerplate code.
17+
18+
#### Example
19+
20+
```yaml
21+
generates:
22+
openapi.yaml:
23+
module: '@apexlang/codegen/openapiv3'
24+
visitorClass: OpenAPIV3Visitor
25+
```
26+
27+
#### Configuration
28+
29+
Not applicable

‎docs/generators/proto.md

+48
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,48 @@
1+
---
2+
title: Protocol Buffers
3+
---
4+
5+
# Protocol Buffers
6+
7+
Generate `.proto` files with gRPC services included.
8+
9+
## ProtoVisitor
10+
11+
<p>
12+
<span className="badgeDarkBlue">Transport layer</span>
13+
<a href="https://github.com/apexlang/codegen/blob/main/src/proto/proto_visitor.ts" target="_blank" rel="noopener noreferrer">Source code <svg width="13.5" height="13.5" aria-hidden="true" viewBox="0 0 24 24" class="iconExternalLink_node_modules-@docusaurus-theme-classic-lib-theme-Icon-ExternalLink-styles-module"><path fill="currentColor" d="M21 13v10h-21v-19h12v2h-10v15h17v-8h2zm3-12h-10.988l4.035 4-6.977 7.07 2.828 2.828 6.977-7.07 4.125 4.172v-11z"></path></svg></a>
14+
</p>
15+
16+
This visitor creates a `.proto` file for all `@service` interfaces using [protoc-gen-go](https://grpc.io/docs/languages/go/quickstart/). This should be used in conjunction with a language specific wrapper generator (for example, [GRPCVisitor for Go](go#grpcvisitor)) to generate the boilerplate code.
17+
18+
#### Example
19+
20+
```yaml
21+
generates:
22+
proto/service.proto:
23+
module: '@apexlang/codegen/proto'
24+
visitorClass: ProtoVisitor
25+
config:
26+
options:
27+
go_package: github.com/apexlang/outputtest/proto
28+
runAfter:
29+
- command: |
30+
protoc
31+
--go_out=.
32+
--go_opt=paths=source_relative
33+
--go-grpc_out=.
34+
--go-grpc_opt=paths=source_relative
35+
proto/service.proto
36+
```
37+
38+
#### Configuration
39+
40+
| Field | Description |
41+
| ----------------------- | --------------------------------------------- |
42+
| `options` | A map of option names to values to include |
43+
44+
:::info
45+
46+
You can use `runAfter` to execute `protoc` after the `.proto` is generated which will fully generate all your boilerplate code.
47+
48+
:::

‎docs/getting-started.mdx

+1-1
Original file line numberDiff line numberDiff line change
@@ -95,7 +95,7 @@ Now your environment is supercharged for cloud-native application development!
9595
<div>
9696
<Link
9797
className="button button--secondary button--lg"
98-
to="/docs/tutorial-basics/create-a-spec">
98+
to="/docs/tutorial/create-a-spec">
9999
Begin the tutorial - 5min ⏱️
100100
</Link>
101101
&nbsp;&nbsp;or&nbsp;&nbsp;

‎docs/tutorial-extras/img/docsVersionDropdown.png

-24.8 KB
Binary file not shown.

‎docs/tutorial-extras/img/localeDropdown.png

-27.2 KB
Binary file not shown.

‎docs/tutorial-extras/project-templates.md

-7
This file was deleted.

‎docs/tutorial-basics/_category_.json renamed to ‎docs/tutorial/_category_.json

+1-1
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
{
2-
"label": "Tutorial - Basics",
2+
"label": "Tutorial",
33
"position": 3,
44
"link": {
55
"type": "generated-index",

‎docs/tutorial-basics/configure-codegen.mdx renamed to ‎docs/tutorial/configure-codegen.mdx

+2-2
Original file line numberDiff line numberDiff line change
@@ -77,8 +77,8 @@ generates:
7777
module: '@apexlang/codegen/openapiv3'
7878
visitorClass: OpenAPIV3Visitor
7979
proto/service.proto:
80-
module: '@apexlang/codegen/grpc'
81-
visitorClass: GRPCVisitor
80+
module: '@apexlang/codegen/proto'
81+
visitorClass: ProtoVisitor
8282
config:
8383
options:
8484
go_package: "github.com/myorg/myapps/pkg/urlshortener"

‎docs/tutorial-basics/congratulations.md renamed to ‎docs/tutorial/congratulations.md

+3-3
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,7 @@ sidebar_position: 6
66

77
You have just learned the **basics of Apex** and described a simple **URL Shortener** service. Obviously, this service is extremely minimal and does not implement common requirements like authorization and distributed tracing. Typically, organizations have their own way of structuring APIs that fit their own policies and specific needs. The idea behind Apex is to provide flexible tools that can be used as a foundation for implementing *any* kind of tailored output.
88

9-
Have **15 more minutes**? Take a look at **[code generators](/docs/tutorial-extras/custom-generators)** and **[project templates](/docs/tutorial-extras/project-templates)**.
9+
Have **15 more minutes**? Take a look at **[code generators](/docs/customization/custom-generators)** and **[project templates](/docs/customization/project-templates)**.
1010

1111
Anything **unclear** or **buggy** in this tutorial? [Please report it!](https://github.com/apexlang/apexlang.io/issues)
1212

@@ -15,6 +15,6 @@ Run into a case where the code generator didn't produce what it should? [Please
1515
## What's next?
1616

1717
- Read the [language specification](/docs/specification)
18-
- Create a [custom generators](/docs/tutorial-extras/custom-generators)
19-
- Create a [project template](/docs/tutorial-extras/project-templates)
18+
- Create a [custom generators](/docs/customization/custom-generators)
19+
- Create a [project template](/docs/customization/project-templates)
2020
- Get involved in the [Apex Community](https://apexlang.io/community/support)

‎docs/tutorial-basics/create-a-spec.md renamed to ‎docs/tutorial/create-a-spec.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -76,4 +76,4 @@ Let's summarize what is captured in the **URL Shortener** service specification
7676
* `URL` is the data structure returned by the operations in `Shortener`. The `@n` annotations on fields and parameters specify the field number and required for serialization formats like Protobuf. The `@rename` annotation is used to override the field name to fit the naming standards of a language.
7777
* Every role, operation, type, and field has a description (enclosed in "") which passes through to generated files. For generated code, these descriptions are available inside your IDE.
7878

79-
This example highlights common elements you will use in your own specifications. If you are curious if you can create your own imports and directives, the answer is Yes! Apex is designed for extensibility. That will be covered later in [custom generators](/docs/tutorial-extras/custom-generators.md).
79+
This example highlights common elements you will use in your own specifications. If you are curious if you can create your own imports and directives, the answer is Yes! Apex is designed for extensibility. That will be covered later in [custom generators](/docs/customization/custom-generators.md).

‎docs/tutorial-basics/generate-api-boilerplate.mdx renamed to ‎docs/tutorial/generate-api-boilerplate.mdx

+4-4
Original file line numberDiff line numberDiff line change
@@ -10,7 +10,7 @@ import TabItem from '@theme/TabItem';
1010

1111
Wouldn't it be cool if you could also generate all the boilerplate code for your API? You are about to do just that using Go.
1212

13-
:::note
13+
:::info
1414

1515
You will need to have [Go installed](https://go.dev/dl/) and in your PATH. Additionally, you need [`protoc`](https://grpc.io/docs/protoc-installation/) and [`protoc-gen-go` installed](https://grpc.io/docs/languages/go/quickstart/).
1616

@@ -37,8 +37,8 @@ generates:
3737
module: '@apexlang/codegen/openapiv3'
3838
visitorClass: OpenAPIV3Visitor
3939
proto/service.proto:
40-
module: '@apexlang/codegen/grpc'
41-
visitorClass: GRPCVisitor
40+
module: '@apexlang/codegen/proto'
41+
visitorClass: ProtoVisitor
4242
config:
4343
options:
4444
go_package: github.com/apexlang/getting-started/proto
@@ -81,7 +81,7 @@ generates:
8181
visitorClass: MainVisitor
8282
```
8383
84-
:::note
84+
:::info
8585
8686
Now we are using some more options:
8787

‎docs/tutorial-basics/generate-api-specs.md renamed to ‎docs/tutorial/generate-api-specs.md

File renamed without changes.

0 commit comments

Comments
 (0)