Skip to content

Commit

Permalink
feat: init repo with baseline go generator template (#1)
Browse files Browse the repository at this point in the history 
* adding baseline template files

* Adding template files

* Adding template files

* Updated readme

* Restructing

* Create PULL_REQUEST_TEMPLATE.md

* Delete PULL_REQUEST_TEMPLATE.md

* Adding initial contribution guidelines

* Modified generate code

* Updated api docs template

* Updated template

* Update api_doc.mustache

* Modified template

* Updated doc

* Updated formatting

* Fixing build issues with go code

* Fixing issues with generated code

* Cleanup

* Cleanups and replacing basenames with paramnames

* Cleanups and replacing basenames with paramnames

Co-authored-by: shwetharadhakrishna <[email protected]>
  • Loading branch information
@shwetha-manvinkurke
shwetha-manvinkurke and shwetharadhakrishna authored Jan 26, 2021
1 parent 7f3e143 commit f7c84ec
Show file tree
Hide file tree
Showing 17 changed files with 1,124 additions and 2 deletions.
144 changes: 144 additions & 0 deletions CONTRIBUTING.md
View file
Original file line number Diff line number Diff line change
@@ -1 +1,145 @@
# Contributing to `twilio-oai-generator`

We'd love for you to contribute to our source code and to make `twilio-oai-generator`
even better than it is today! Here are the guidelines we'd like you to follow:

- [Code of Conduct](#coc)
- [Question or Problem?](#question)
- [Issues and Bugs](#issue)
- [Feature Requests](#feature)
- [Documentation fixes](#docs)
- [Submission Guidelines](#submit)
- [Coding Rules](#rules)


## <a name="coc"></a> Code of Conduct

Help us keep `twilio-oai-generator` open and inclusive. Please be kind to and considerate
of other developers, as we all have the same goal: make `twilio-oai-generator` as good as
it can be.

## <a name="question"></a> Got an API/Product Question or Problem?

If you have questions about how to use `twilio-oai-generator`, please see our
[docs][docs-link], and if you don't find the answer there, please contact
[[email protected]](mailto:[email protected]) with any issues you have.

## <a name="issue"></a> Found an Issue?

If you find a bug in the source code or a mistake in the documentation, you can
help us by submitting [an issue][issue-link].

**Please see the [Submission Guidelines](#submit) below.**

## <a name="feature"></a> Want a Feature?

You can request a new feature by submitting an issue to our
[GitHub Repository][github]. If you would like to implement a new feature then
consider what kind of change it is:

* **Major Changes** that you wish to contribute to the project should be
discussed first with `twilio-oai-generator` contributors in an issue or pull request so
that we can develop a proper solution and better coordinate our efforts,
prevent duplication of work, and help you to craft the change so that it is
successfully accepted into the project.
* **Small Changes** can be crafted and submitted to the
[GitHub Repository][github] as a Pull Request.

## <a name="docs"></a> Want a Doc Fix?

If you want to help improve the docs in the helper library, it's a good idea to
let others know what you're working on to minimize duplication of effort. Create
a new issue (or comment on a related existing one) to let others know what
you're working on.

For large fixes, please build and test the documentation before submitting the
PR to be sure you haven't accidentally introduced layout or formatting issues.


## <a name="submit"></a> Submission Guidelines

### Submitting an Issue
Before you submit your issue search the archive, maybe your question was already
answered.

If your issue appears to be a bug, and hasn't been reported, open a new issue.
Help us to maximize the effort we can spend fixing issues and adding new
features by not reporting duplicate issues. Providing the following information
will increase the chances of your issue being dealt with quickly:

* **Overview of the Issue** - if an error is being thrown a non-minified stack
trace helps
* **Motivation for or Use Case** - explain why this is a bug for you
* **`twilio-oai-generator` Version(s)** - is it a regression?
* **Operating System (if relevant)** - is this a problem with all systems or
only specific ones?
* **Reproduce the Error** - provide an isolated code snippet or an unambiguous
set of steps.
* **Related Issues** - has a similar issue been reported before?
* **Suggest a Fix** - if you can't fix the bug yourself, perhaps you can point
to what might be causing the problem (line of code or commit)

**If you get help, help others. Good karma rules!**

### Submitting a Pull Request
Before you submit your pull request consider the following guidelines:

* Search [GitHub][github] for an open or closed Pull Request that relates to
your submission. You don't want to duplicate effort.
* Make your changes in a new git branch:

```shell
git checkout -b my-fix-branch main
```

* Create your patch, **including appropriate test cases**.
* Follow our [Coding Rules](#rules).
* Run the full `twilio-oai-generator` test suite (aliased by `make test`), and ensure
that all tests pass.
* Commit your changes using a descriptive commit message.

```shell
git commit -a
```
Note: the optional commit `-a` command line option will automatically "add"
and "rm" edited files.

* Build your changes locally to ensure all the tests pass:

```shell
make test
```

* Push your branch to GitHub:

```shell
git push origin my-fix-branch
```

In GitHub, send a pull request to `twilio-oai-generator:main`.
If we suggest changes, then:

* Make the required updates.
* Re-run the `twilio-oai-generator` test suite to ensure tests are still passing.
* Commit your changes to your branch (e.g. `my-fix-branch`).
* Push the changes to your GitHub repository (this will update your Pull Request).

That's it! Thank you for your contribution!
#### After your pull request is merged
After your pull request is merged, you can safely delete your branch and pull
the changes from the main (upstream) repository.
## <a name="rules"></a> Coding Rules
To ensure consistency throughout the source code, keep these rules in mind as
you are working:
* All features or bug fixes **must be tested** by one or more tests.
* All classes and methods **must be documented**.
[docs-link]: https://github.com/twilio/twilio-oai-generator/README.md
[issue-link]: https://github.com/twilio/twilio-oai-generator/issues/new
[github]: https://github.com/twilio/twilio-oai-generator
83 changes: 81 additions & 2 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,2 +1,81 @@
# twilio-oai-generator
Twilio OpenAPI client generator
# OpenAPI Generator for the [twilio-go](https://github.com/twilio/twilio-go/) library

## Overview
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.

## What's OpenAPI
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](https://github.com/OAI/OpenAPI-Specification) for additional information about the OpenAPI project, including additional libraries with support for other languages and more.

## How do I use this?
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](https://openapi-generator.tech):

For mac/linux:
```
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)

For Windows users, 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.

## But how do I modify this?
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.
128 changes: 128 additions & 0 deletions pom.xml
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,128 @@
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">
<modelVersion>4.0.0</modelVersion>
<groupId>org.openapitools</groupId>
<artifactId>twilio-go-openapi-generator</artifactId>
<packaging>jar</packaging>
<name>twilio-go-openapi-generator</name>
<version>1.0.0</version>
<build>
<plugins>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-enforcer-plugin</artifactId>
<version>3.0.0-M1</version>
<executions>
<execution>
<id>enforce-maven</id>
<goals>
<goal>enforce</goal>
</goals>
<configuration>
<rules>
<requireMavenVersion>
<version>2.2.0</version>
</requireMavenVersion>
</rules>
</configuration>
</execution>
</executions>
</plugin>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-surefire-plugin</artifactId>
<version>2.12</version>
<configuration>
<systemProperties>
<property>
<name>loggerPath</name>
<value>conf/log4j.properties</value>
</property>
</systemProperties>
<argLine>-Xms512m -Xmx1500m</argLine>
<parallel>methods</parallel>
<forkMode>pertest</forkMode>
</configuration>
</plugin>

<!-- attach test jar -->
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-jar-plugin</artifactId>
<version>2.2</version>
<executions>
<execution>
<goals>
<goal>jar</goal>
<goal>test-jar</goal>
</goals>
</execution>
</executions>
<configuration>
</configuration>
</plugin>

<plugin>
<groupId>org.codehaus.mojo</groupId>
<artifactId>build-helper-maven-plugin</artifactId>
<version>3.0.0</version>
<executions>
<execution>
<id>add_sources</id>
<phase>generate-sources</phase>
<goals>
<goal>add-source</goal>
</goals>
<configuration>
<sources>
<source>
src/main/java</source>
</sources>
</configuration>
</execution>
<execution>
<id>add_test_sources</id>
<phase>generate-test-sources</phase>
<goals>
<goal>add-test-source</goal>
</goals>
<configuration>
<sources>
<source>
src/test/java</source>
</sources>
</configuration>
</execution>
</executions>
</plugin>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-compiler-plugin</artifactId>
<version>3.6.1</version>
<configuration>
<source>1.8</source>
<target>1.8</target>
</configuration>
</plugin>
</plugins>
</build>
<dependencies>
<dependency>
<groupId>org.openapitools</groupId>
<artifactId>openapi-generator</artifactId>
<version>${openapi-generator-version}</version>
<scope>provided</scope>
</dependency>
<dependency>
<groupId>junit</groupId>
<artifactId>junit</artifactId>
<version>${junit-version}</version>
</dependency>
</dependencies>
<properties>
<project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
<openapi-generator-version>5.0.0-beta2</openapi-generator-version>
<maven-plugin-version>1.0.0</maven-plugin-version>
<junit-version>4.8.1</junit-version>
</properties>
</project>
Loading

0 comments on commit f7c84ec

Please sign in to comment.