Skip to content

Commit 1cf390f

Browse files
author
Jamie Tanna
committed
sq
1 parent 6e8a1dd commit 1cf390f

File tree

2 files changed

+84
-44
lines changed

2 files changed

+84
-44
lines changed

‎CONTRIBUTING.md‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -55,6 +55,9 @@ Now, please note that significant changes to generated code are likley to **??**
5555

5656
**Should introduce a flag if possible**
5757

58+
**Opt-in by default?**
59+
60+
5861
### Minimal reproductions
5962

6063
### Before you raise a PR

‎README.md‎

Lines changed: 81 additions & 44 deletions
Original file line numberDiff line numberDiff line change
@@ -1,47 +1,16 @@
11
# `oapi-codegen`
22

3-
`oapi-codegen` is a library, and command-line tool, to convert OpenAPI API specifications to Go code, be it server-side implementations, API clients, or simply models.
3+
`oapi-codegen` is a command-line tool and library, to convert OpenAPI API specifications to Go code, be it server-side implementations, API clients, or simply HTTP models.
44

55
`oapi-codegen` aims to reduce some of the tedious boilerplate that can be found when building or interacting with APIs, and focusses on:
66

77
- idiomatic Go, where possible
88
- fairly simple generated code, erring on the side of duplicate code over nicely refactored code
99
- supporting as much of OpenAPI 3.x as is possible, alongside Go's type system
1010

11-
⚠️ This README may be for the latest development version, which may contain
12-
unreleased changes. Please ensure you're looking at the README for the latest
13-
release version.
11+
You can read more about our [Design Decisions](#design-decisions) below.
1412

15-
Does not 2.0
16-
17-
## OpenAPI Client and Server Code Generator
18-
19-
```
20-
This package contains a set of utilities for generating Go boilerplate code for
21-
services based on
22-
[OpenAPI 3.0](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md)
23-
API definitions. When working with services, it's important to have an API
24-
contract which servers and clients both implement to minimize the chances of
25-
incompatibilities. It's tedious to generate Go models which precisely correspond to
26-
OpenAPI specifications, so let our code generator do that work for you, so that
27-
you can focus on implementing the business logic for your service.
28-
29-
We have chosen to focus on [Echo](https://github.com/labstack/echo) as
30-
our default HTTP routing engine, due to its speed and simplicity for the generated
31-
stubs. [Chi](https://github.com/go-chi/chi), [Gin](https://github.com/gin-gonic/gin),
32-
[gorilla/mux](https://github.com/gorilla/mux), [Fiber](https://github.com/gofiber/fiber),
33-
[Iris](https://github.com/kataras/iris), and [1.22+ net/http](https://pkg.go.dev/net/http)
34-
have also been added by contributors as additional routers.
35-
We chose Echo because the `Context` object is a mockable interface, and it allows for some advanced
36-
testing.
37-
38-
This package tries to be too simple rather than too generic, so we've made some
39-
design decisions in favor of simplicity, knowing that we can't generate strongly
40-
typed Go code for all possible OpenAPI Schemas. If there is a way to accomplish
41-
something via utility code or reflection, it's probably a better approach than
42-
code generation, which is fragile due to the very dynamic nature of OpenAPI and
43-
the very static nature of Go.
44-
```
13+
⚠️ This README may be for the latest development version, which may contain unreleased changes. Please ensure you're looking at the README for the latest release version.
4514

4615
## Install
4716

@@ -60,7 +29,11 @@ import (
6029
)
6130
```
6231

63-
Then, each **??**
32+
Then, each invocation of `oapi-codegen` would be used like so:
33+
34+
```go
35+
//go:generate go run github.com/deepmap/oapi-codegen/v2/cmd/oapi-codegen --config=config.yaml ../../api.yaml
36+
```
6437

6538
Alternatively, you can install it as a binary with:
6639

@@ -69,17 +42,23 @@ $ go install github.com/deepmap/oapi-codegen/v2/cmd/oapi-codegen@latest
6942
$ oapi-codegen -version
7043
```
7144

45+
Which then means you can invoke it like so:
46+
47+
```go
48+
//go:generate go run oapi-codegen --config=config.yaml ../../api.yaml
49+
```
50+
7251
## Usage
7352

74-
`oapi-codegen` is largely **??**.
53+
`oapi-codegen` is largely configured using a YAML configuration file, to simplify the number of flags that users need to remember.
7554

7655
For full https://pkg.go.dev/github.com/deepmap/oapi-codegen/v2/pkg/codegen#Configuration
7756

7857
## Features
7958

8059
`oapi-codegen` supports:
8160

82-
- Generating server-side boilerplate for [a number of servers]
61+
- Generating server-side boilerplate for [a number of servers] TODO
8362
- Generating client API boilerplate
8463
- Generating the types
8564
- Splitting **??**
@@ -93,6 +72,18 @@ For full https://pkg.go.dev/github.com/deepmap/oapi-codegen/v2/pkg/codegen#Confi
9372
- Single-file output
9473
- Support multiple OpenAPI files by having a package-per-file
9574
- **??**
75+
- Support of OpenAPI 3.x
76+
- OpenAPI 3.1 support is [awaiting upstream support](https://github.com/deepmap/oapi-codegen/issues/373)
77+
- Note that this does not include OpenAPI 2.0 (aka Swagger)
78+
79+
```
80+
This package tries to be too simple rather than too generic, so we've made some
81+
design decisions in favor of simplicity, knowing that we can't generate strongly
82+
typed Go code for all possible OpenAPI Schemas. If there is a way to accomplish
83+
something via utility code or reflection, it's probably a better approach than
84+
code generation, which is fragile due to the very dynamic nature of OpenAPI and
85+
the very static nature of Go.
86+
```
9687

9788
### Generating server-side boilerplate
9889

@@ -116,42 +107,88 @@ To provide you a fully Test Driven Development style test harness, you could use
116107

117108
<tr>
118109
<th>
119-
Server name
110+
Server
120111
</th>
121112
<th>
122-
Configuration **??**
113+
<code>generate</code> flag to enable code generation
123114
</th>
124115
</tr>
125116

126117
<tr>
127118
<td>
119+
120+
[Chi](https://github.com/go-chi/chi)
121+
128122
</td>
129123
<td>
130-
<code> </code>
124+
<code>chi-server</code>
131125
</td>
132126
</tr>
133127

134128
<tr>
135129
<td>
130+
131+
[Echo](https://github.com/labstack/echo)
132+
136133
</td>
137134
<td>
138-
<code> </code>
135+
<code>echo-server</code>
139136
</td>
140137
</tr>
141138

142139
<tr>
143140
<td>
141+
142+
[Fiber](https://github.com/gofiber/fiber)
143+
144+
</td>
145+
<td>
146+
<code>fiber-server</code>
147+
</td>
148+
</tr>
149+
150+
151+
<tr>
152+
<td>
153+
154+
[Gin](https://github.com/gin-gonic/gin)
155+
144156
</td>
145157
<td>
146-
<code> </code>
158+
<code>gin-server</code>
147159
</td>
148160
</tr>
149161

150162
<tr>
151163
<td>
164+
165+
[gorilla/mux](https://github.com/gorilla/mux)
166+
167+
</td>
168+
<td>
169+
<code>gorilla-server</code>
170+
</td>
171+
</tr>
172+
173+
<tr>
174+
<td>
175+
176+
[Iris](https://github.com/kataras/iris)
177+
178+
</td>
179+
<td>
180+
<code>iris-server</code>
181+
</td>
182+
</tr>
183+
184+
<tr>
185+
<td>
186+
187+
[1.22+ `net/http`](https://pkg.go.dev/net/http)
188+
152189
</td>
153190
<td>
154-
<code> </code>
191+
<code>std-http-server</code>
155192
</td>
156193
</tr>
157194

@@ -225,7 +262,7 @@ Got one to add? Please raise a PR!
225262
## Overview
226263

227264
We're going to use the OpenAPI example of the
228-
[Expanded Petstore](https://github.com/OAI/OpenAPI-Specification/blob/master/examples/v3.0/petstore-expanded.yaml)
265+
[Expanded Petstore](https://github.com/OAI/OpenAPI-Specification/blob/main/examples/v3.0/petstore-expanded.yaml)
229266
in the descriptions below, please have a look at it.
230267

231268
In order to create a Go server to serve this exact schema, you would have to

0 commit comments

Comments
 (0)