openapi3-code-generator
How to use?
- install cabal
cabal update
cabal install openapi3-code-generator
openapi3-code-generator-exe my_specification.yml
An out
directory is created with the generated code. Hint you can use --output-dir
to specify another output directory.
You can use openapi3-code-generator --help
to list all CLI options.
If openapi3-code-generator-exe
is not found, you may not have added the cabal bin to your PATH
. Execute ~/.local/bin/openapi3-code-generator-exe
instead.
How to run from source
- install stack
stack run -- --help
Example package
In the folder example
is a package that uses the generated code from specifications/petstore.yml
.
You can run stack test
inside the example
directory to run the code, it calls the server "https://petstore.swagger.io/v2" with some sample data.
https://github.com/Haskell-OpenAPI-Code-Generator/Stripe-Haskell-Library uses this code generator to generate a Stripe API client.
Documentation
The documentation for the code can be found at https://hackage.haskell.org/package/openapi3-code-generator This package was created as part of a bachelor thesis. public thesis
Large specifications
For large specifications some modules (CyclicTypes.hs for example) can get pretty big. It may be necessary to use --fast
with stack build --fast
to build the code.
Module structure of the generated code.
All symbols are globally unique and are reexported in the module OpenAPI
(Module name can be changed with --module-name
).
To reduce compile time, the code is split up into multiple modules.
Mainly for every operation and for every schema.
Troubleshooting naming conflicts
Naming conflicts can happen, sometimes a little manual adjustment is needed. With the following options naming conflicts can be resolved. It can happen, that the names get so long, that they are longer than the file system supports.
property-type-suffix
response-type-suffix
response-body-type-suffix
request-body-type-suffix
use-numbered-variant-constructors
convert-to-camel-case
Limitations
The following features are not supported
- links
- callbacks
- Only references to
components
are supported - Only JSON is supported for both sending and receiving data.
application/x-www-form-urlencoded
can only be used to send data. - Some circular references in the schemas. For example if an
allOf
contains itself - Parameters not in
path
orquery
additionalProperties
not
schemaswriteOnly
andreadOnly
multipleOf
maximum
exclusiveMaximum
minimum
exclusiveMinimum
minLength
maxItems
minItems
uniqueItems
maxProperties
minProperties
xml
Development
Re-generate the code found in the example directory if you made changes to the output generator. You can do this using the example-configuration.yml:
openapi3-code-generator-exe --configuration example-configuration.yml
Also make sure that the tests there run fine:
cd example
stack test
Also adapt golden tests. The script to generate these can found in .cicleci/test_golden. As these assume to be run as root you have to manually execute the commands listed there, e.g.:
stack build # just to make sure the built executable is up-to-date
.circleci/test_golden update