Oapi-codegen: Difference between revisions

From NovaOrdis Knowledge Base
Jump to navigation Jump to search
 
(36 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]]
* [[A Simple CRUD REST Application with OpenAPI#Overview|A Simple CRUD REST Application with OpenAPI]]
* [[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 28: Line 30:
</syntaxhighlight>
</syntaxhighlight>


==<tt>make</tt> Support==
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'>
<syntaxhighlight lang='make'>
.PHONY: generate_oapi_artifacts
.PHONY: generate_oapi_artifacts
Line 48: Line 52:


==Type Generation==
==Type Generation==
See: {{Internal|OpenAPI_Specification_Schemas#Overview|OpenAPI Specification Schemas}}
Generate the types declared in the <code>[[OpenAPI_Specification_Schemas#Overview|/components/schemas]]</code> section of the OpenAPI specification.
==Code Generation for OpenAPI Specification Path/Operation Combinations==
 
{{Internal|OpenAPI_Specification_Path#Server_Code_Generation_for_Path/Operation_Combinations|OpenAPI Specification Path &#124; Server Code Generation for Path/Operation Combinations}}
<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>


Implement the handlers and register them with <code>[[Labstack/echo|echo]]</code>: {{Internal|Labstack/echo#Registering_Handlers_Generated_by_oapi-codegen_from_an_OpenAPI_Specification|echo &#124; Registering Handlers Generated by <tt>oapi-codegen</tt> from an OpenAPI Specification}}
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=
=Options=
Line 59: Line 90:
==<tt>-generate</tt>==
==<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".
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===
===<tt>types</tt>===
Generate the types declared in the <code>[[OpenAPI_Specification_Schemas#Overview|/components/schemas]]</code> section of the OpenAPI specification.
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'>
<syntaxhighlight lang='bash'>
oapi-codegen -generate types -package petstore ./petstore-expanded.yaml > ./internal/petstore/types.gen.go
oapi-codegen -generate chi-server -package petstore ./petstore.yaml > ./internal/petstore/server.gen.go
</syntaxhighlight>
</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?


===spec===
</font>
Generates this:
Generates this:
<syntaxhighlight lang='go'>
<syntaxhighlight lang='go'>
Line 81: Line 120:
func GetSwagger() (swagger *openapi3.T, err error) {...}
func GetSwagger() (swagger *openapi3.T, err error) {...}
</syntaxhighlight>
</syntaxhighlight>
===server===
Default, generates server code for the [[Labstack/echo|echo]] HTTP server.
===chi-server===
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.
===client===

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) {...}
Retrieved from "https://kb.novaordis.com/index.php?title=Oapi-codegen&oldid=109180"