OpenAPI Generator for the twilio-go library
This is a boiler-plate project to generate your own project derived from an OpenAPI specification.
Its goal is to get you started with the basic plumbing, so you can put in your own logic. It won't work without your changes applied. Continue reading this doc to get more details on how to do that.
The goal of OpenAPI is to define a standard, language-agnostic interface to REST APIs which allows both humans and computers to discover and understand the capabilities of the service without access to source code, documentation, or through network traffic inspection.
When properly described with OpenAPI, a consumer can understand and interact with the remote service with a minimal amount of implementation logic. Similar to what interfaces have done for lower-level programming, OpenAPI removes the guesswork in calling the service.
Check out OpenAPI-Spec for additional information about the OpenAPI project, including additional libraries with support for other languages and more.
Clone this repo into your local machine. It will include:
.
|- README.md // this file
|- pom.xml // build script
|-- src
|--- main
|---- java
|----- com.twilio.oai.TwilioGoGenerator.java // generator file
|---- resources
|----- twilio-go // template files
|----- META-INF
|------ services
|------- org.openapitools.codegen.CodegenConfig
You will need to make changes in at least the following:
TwilioGoGenerator.java
Templates in this folder:
src/main/resources/twilio-go
Once modified, you can run this:
mvn package
In your generator project. A single jar file will be produced in target
. You can now use that with OpenAPI Generator:
java -cp /path/to/openapi-generator-cli.jar:/path/to/your.jar org.openapitools.codegen.OpenAPIGenerator generate -g twilio-go -i /path/to/openapi.yaml -o ./test
(Do not forget to replace the values /path/to/openapi-generator-cli.jar
, /path/to/your.jar
and /path/to/openapi.yaml
in the previous command)
Here is an example script to generate twilio-go from our OpenAPI specification: build_twilio_go.py.
You will need to use ;
instead of :
in the classpath, e.g.
java -cp /path/to/openapi-generator-cli.jar;/path/to/your.jar org.openapitools.codegen.OpenAPIGenerator generate -g twilio-go -i /path/to/openapi.yaml -o ./test
Now your templates are available to the client generator, and you can write output values.
The TwilioGoGenerator.java
has comments in it--lots of comments. There is no good substitute for reading the code more, though. See how the TwilioGoGenerator
implements CodegenConfig
. That class has the signature of all values that can be overridden.
You can also step through TwilioGoGenerator.java in a debugger. Just debug the JUnit test in DebugCodegenLauncher. That runs the command line tool and lets you inspect what the code is doing.
For the templates themselves, you have a number of values available to you for generation. You can execute the java
command from above while passing different debug flags to show the object you have available during client generation:
# The following additional debug options are available for all codegen targets:
# -DdebugOpenAPI prints the OpenAPI Specification as interpreted by the codegen
# -DdebugModels prints models passed to the template engine
# -DdebugOperations prints operations passed to the template engine
# -DdebugSupportingFiles prints additional data passed to the template engine
java -DdebugOperations -cp /path/to/openapi-generator-cli.jar:/path/to/your.jar org.openapitools.codegen.OpenAPIGenerator generate -g twilio-go -i /path/to/openapi.yaml -o ./test
Will, for example, output the debug info for operations.
You can use this info in the api.mustache
file.
To run the unit tests or integration tests locally you need complete the following steps:
- Install the prism CLI to run the integration tests locally.
- Run
make test-docker
from the root directory. - Navigate to the
oai.yaml
located inexamples/go
and in a new terminal tab run the commandprism mock oai.yaml
. - In
examples/go/test/api_test.go
TestMain function changetestClient.BaseURL = "http://prism_twilio:4010"
totestClient.BaseURL = "http://localhost:4010"
. - Run the tests locally in your terminal with the command
go test ./... -v
while insideexamples/go
.
To generate twilio-go
from twilio-oai
- Clone this repo
- Clone twilio-oai
- Clone twilio-go
- Navigate to your local
twilio-oai-generator
and runmake install
Update <path to>
and execute the following from the root of this repo:
- To generate the entire suite, run
make install && python3 examples/build_twilio_go.py <path to>/twilio-oai/spec/yaml <path to>/twilio-go
- To generate the provider for a single domain such as studio, run
make install && python3 examples/build_twilio_go.py <path to>/twilio-oai/spec/yaml/twilio_studio_v2.yaml <path to>/twilio-go
- Clone this repo
- Clone twilio-oai
- Clone terraform-provider-twilio
- Navigate to your local
twilio-oai-generator
and runmake install
Update <path to>
and execute the following from the root of this repo:
- To generate the entire suite, run
make install && python3 examples/build_twilio_go.py <path to>/twilio-oai/spec/yaml <path to>/terraform-provider-twilio -l terraform
- To generate the provider for a single domain such as studio, run
make install && python3 examples/build_twilio_go.py <path to>/twilio-oai/spec/yaml/twilio_studio_v2.yaml <path to>/terraform-provider-twilio -l terraform
- Run
python3 examples/build_twilio_go.py -h
to see more details