Oapi-codegen: Difference between revisions

From NovaOrdis Knowledge Base
Jump to navigation Jump to search
 
(53 intermediate revisions by the same user not shown)
Line 2: Line 2:
* https://github.com/deepmap/oapi-codegen
* https://github.com/deepmap/oapi-codegen
=Internal=
=Internal=
* [[Go OpenAPI#Subjects|Go OpenAPI]]
* [[OpenAPI_Code_Generators#Go|OpenAPI Code Generators]]
* [[OpenAPI_Specification_Path#Operation_Declaration_and_Implementation_Examples|OpenAPI Operation Declaration and Implementation Examples]]
 
=Overview=
=Overview=
<font color=darkkhaki>Rewrite this after using it for two different services.</font>


=Installation=
=Installation=
Line 17: Line 21:
The installation will place the package under <code>$GOPATH/pkg/mod/cache/download/github.com/deepmap</code> and <code>$GOPATH/pkg/mod/github.com/deepmap</code>, will compile the binary and place it under <code>~/go/bin</code>.
The installation will place the package under <code>$GOPATH/pkg/mod/cache/download/github.com/deepmap</code> and <code>$GOPATH/pkg/mod/github.com/deepmap</code>, will compile the binary and place it under <code>~/go/bin</code>.


=Generate Server Code=
=Generate Code=
=Generate Client Code=
 
Generate client and server code:
 
<syntaxhighlight lang='bash'>
oapi-codegen -package petstore ./petstore-expanded.yaml > ./internal/petstore/petstore.gen.go
go mod tidy
</syntaxhighlight>
 
The [[#Type_Generation|types]], spec and [[#Server_Code_Generation|server code]] can live in different packages. For suggestions on layout, see: {{Internal|Go_Project#api|Go Project Layout}}
 
==Makefile Support==
<syntaxhighlight lang='make'>
.PHONY: generate_oapi_artifacts
 
generate_oapi_artifacts: internal/petstore/spec.gen.go internal/petstore/types.gen.go internal/petstore/server.gen.go internal/petstore/client.gen.go
 
internal/petstore/spec.gen.go: ./petstore.yaml
oapi-codegen -generate spec -package petstore $< > $@
 
internal/petstore/types.gen.go: ./petstore.yaml
oapi-codegen -generate types -package petstore $< > $@
 
internal/petstore/server.gen.go: ./petstore.yaml
oapi-codegen -generate server -package petstore $< > $@
 
internal/petstore/client.gen.go: ./petstore.yaml
oapi-codegen -generate client -package petstore $< > $@
</syntaxhighlight>
 
==Type Generation==
Generate the types declared in the <code>[[OpenAPI_Specification_Schemas#Overview|/components/schemas]]</code> section of the OpenAPI specification.
 
<syntaxhighlight lang='bash'>
oapi-codegen -generate types -package petstore ./petstore-expanded.yaml > ./api/openapi-types.gen.go
</syntaxhighlight>
 
Also see: {{Internal|OpenAPI_Specification_Schemas#Overview|OpenAPI Specification Schemas}}
 
==<span id='Code_Generation_for_OpenAPI_Specification_Path/Operation_Combinations'></span>Server Code Generation==
{{External|https://github.com/deepmap/oapi-codegen#generated-server-boilerplate}}
 
<font color=darkkhaki>
TODO:
* Understand and document "strict server"
</font>
 
By default, <code>oapi-codegen</code> generates server code for the [[Labstack/echo|echo]] HTTP server.
<syntaxhighlight lang='bash'>
oapi-codegen -generate server -package petstore ./petstore.yaml > ./internal/petstore/server.gen.go
</syntaxhighlight>
For an example of how to set up an <code>echo</code> server with the generated code, see: {{Internal|Labstack/echo#Registering_Handlers_Generated_by_oapi-codegen_from_an_OpenAPI_Specification|echo Server with oapi-codegen Code}}
For OpenAPI specification examples and their corresponding generated server code see: {{Internal|OpenAPI_Specification_Path#Operation_Declaration_and_Implementation_Examples|OpenAPI Examples}}
 
==Client Code Generation==
{{External|https://github.com/deepmap/oapi-codegen#generated-client-boilerplate}}
The client code must be generated in the same package as the generated types, because it refers to them. See [[#Type_Generation|Type Generation]] above.
<syntaxhighlight lang='bash'>
oapi-codegen -generate types -package api ./petstore-expanded.yaml > ./api/openapi-types.gen.go
oapi-codegen -generate client -package api ./petstore-expanded.yaml > ./api/openapi-client.gen.go
</syntaxhighlight>
 
The generator creates <code>ClientInterface</code> and <code>ClientWithResponsesInterface</code> interfaces. <font color=darkkhaki>TODO: Understand and document the difference?</font>
 
=Options=
==<tt>-package</tt>==
The package name for the generated code.
==<tt>-generate</tt>==
Comma-separated list of code to generate; valid options: "types", "client", "chi-server", "server", "gin", "gorilla", "spec", "skip-fmt", "skip-prune", "fiber", "iris". The default is "types,client,server,spec".
===<tt>types</tt>===
See [[#Type_Generation|Type Generation]] above.
===<tt>server</tt>===
See [[#Server_Code_Generation|Server Code Generation]] above.
===<tt>chi-server</tt>===
Generates server code for the chi HTTP server. The code is compatible with <code>[[Go_Package_net/http#Registering_Handlers_Generated_by_oapi-codegen_from_an_OpenAPI_Specification|net/http]]</code> server:
<syntaxhighlight lang='bash'>
oapi-codegen -generate chi-server -package petstore ./petstore.yaml > ./internal/petstore/server.gen.go
</syntaxhighlight>
For an example of how to set up a <code>net/http</code> server with the generated code, see: {{Internal|Go_Package_net/http#Registering_Handlers_Generated_by_oapi-codegen_from_an_OpenAPI_Specification|net/http Server with oapi-codegen Code}}
===<tt>client</tt>===
See [[#Client_Code_Generation|Client Code Generation]] above.
===<tt>spec</tt>===
<font color=darkkhaki>TODO: what is this and how it is useful?
 
</font>
Generates this:
<syntaxhighlight lang='go'>
var swaggerSpec = []string{...}
 
func decodeSpec() ([]byte, error) {...}
 
var rawSpec = decodeSpecCached()
 
func decodeSpecCached() func() ([]byte, error) {...}
 
func PathToRawSpec(pathToFile string) map[string]func() ([]byte, error) {...}
 
func GetSwagger() (swagger *openapi3.T, err error) {...}
</syntaxhighlight>

Latest revision as of 23:10, 8 April 2024

External

Internal

Overview

Rewrite this after using it for two different services.

Installation

Get the latest version from https://github.com/deepmap/oapi-codegen/tags

Then:

go install github.com/deepmap/oapi-codegen/v2/cmd/oapi-codegen@v2.1.0

The installation will place the package under $GOPATH/pkg/mod/cache/download/github.com/deepmap and $GOPATH/pkg/mod/github.com/deepmap, will compile the binary and place it under ~/go/bin.

Generate Code

Generate client and server code:

oapi-codegen -package petstore ./petstore-expanded.yaml > ./internal/petstore/petstore.gen.go
go mod tidy

The types, spec and server code can live in different packages. For suggestions on layout, see:

Go Project Layout

Makefile Support

.PHONY: generate_oapi_artifacts

generate_oapi_artifacts: internal/petstore/spec.gen.go internal/petstore/types.gen.go internal/petstore/server.gen.go internal/petstore/client.gen.go

internal/petstore/spec.gen.go: ./petstore.yaml
	oapi-codegen -generate spec -package petstore $< > $@

internal/petstore/types.gen.go: ./petstore.yaml
	oapi-codegen -generate types -package petstore $< > $@

internal/petstore/server.gen.go: ./petstore.yaml
	oapi-codegen -generate server -package petstore $< > $@

internal/petstore/client.gen.go: ./petstore.yaml
	oapi-codegen -generate client -package petstore $< > $@

Type Generation

Generate the types declared in the /components/schemas section of the OpenAPI specification.

oapi-codegen -generate types -package petstore ./petstore-expanded.yaml > ./api/openapi-types.gen.go

Also see:

OpenAPI Specification Schemas

Server Code Generation

https://github.com/deepmap/oapi-codegen#generated-server-boilerplate

TODO:

  • Understand and document "strict server"

By default, oapi-codegen generates server code for the echo HTTP server.

oapi-codegen -generate server -package petstore ./petstore.yaml > ./internal/petstore/server.gen.go

For an example of how to set up an echo server with the generated code, see:

echo Server with oapi-codegen Code

For OpenAPI specification examples and their corresponding generated server code see:

OpenAPI Examples

Client Code Generation

https://github.com/deepmap/oapi-codegen#generated-client-boilerplate

The client code must be generated in the same package as the generated types, because it refers to them. See Type Generation above.

oapi-codegen -generate types -package api ./petstore-expanded.yaml > ./api/openapi-types.gen.go
oapi-codegen -generate client -package api ./petstore-expanded.yaml > ./api/openapi-client.gen.go

The generator creates ClientInterface and ClientWithResponsesInterface interfaces. TODO: Understand and document the difference?

Options

-package

The package name for the generated code.

-generate

Comma-separated list of code to generate; valid options: "types", "client", "chi-server", "server", "gin", "gorilla", "spec", "skip-fmt", "skip-prune", "fiber", "iris". The default is "types,client,server,spec".

types

See Type Generation above.

server

See Server Code Generation above.

chi-server

Generates server code for the chi HTTP server. The code is compatible with net/http server:

oapi-codegen -generate chi-server -package petstore ./petstore.yaml > ./internal/petstore/server.gen.go

For an example of how to set up a net/http server with the generated code, see:

net/http Server with oapi-codegen Code

client

See Client Code Generation above.

spec

TODO: what is this and how it is useful?

Generates this:

var swaggerSpec = []string{...}

func decodeSpec() ([]byte, error) {...}

var rawSpec = decodeSpecCached()

func decodeSpecCached() func() ([]byte, error) {...}

func PathToRawSpec(pathToFile string) map[string]func() ([]byte, error) {...}

func GetSwagger() (swagger *openapi3.T, err error) {...}