- Search the open issue and closed issue to ensure no one else has reported something similar before.
- The issue should contain details on how to repeat the issue, e.g.
- the OpenAPI Spec for reproducing the issue (:bulb: use Gist to share). If the OpenAPI Spec cannot be shared publicly, it will be hard for the community to help
- version of Swagger Codegen
- language (
-l
in the command line, e.g. java, csharp, php)
- You can also make a suggestion or ask a question by opening an "issue"
- Search the open issue to ensure no one else has reported something similar and no one is actively working on similar proposed change.
- If no one has suggested something similar, open an "issue" with your suggestion to gather feedback from the community.
- It's recommended to create a new git branch for the change
All the code generators can be found in modules/swagger-codegen/src/main/java/io/swagger/codegen/languages
All the templates (mustache) can be found in modules/swagger-codegen/src/main/resources.
For a list of variables available in the template, please refer to this page
Code change should conform to the programming style guide of the respective langauages:
- C#: https://msdn.microsoft.com/en-us/library/vstudio/ff926074.aspx
- Java: https://google.github.io/styleguide/javaguide.html
- JavaScript: https://github.com/airbnb/javascript/tree/master/es5
- Go: https://github.com/golang/go/wiki/CodeReviewComments
- ObjC: https://github.com/NYTimes/objective-c-style-guide
- Perl: http://perldoc.perl.org/perlstyle.html
- PHP: https://github.com/php-fig/fig-standards/blob/master/accepted/PSR-2-coding-style-guide.md
- Python: https://www.python.org/dev/peps/pep-0008/
- Ruby: https://github.com/bbatsov/ruby-style-guide
- Swift: https://developer.apple.com/library/prerelease/ios/documentation/Swift/Conceptual/Swift_Programming_Language/TheBasics.html
- TypeScript: https://github.com/Microsoft/TypeScript/wiki/Coding-guidelines
For other languages, feel free to suggest.
You may find the current code base not 100% conform to the coding style and we welcome contributions to fix those.
To add test cases (optional) covering the change in the code generator, please refer to modules/swagger-codegen/src/test/java/io/swagger/codegen
To test the templates, please perform the following:
- Update the Petstore sample by running the shell script under
bin
folder. For example, run./bin/ruby-petstore.sh
to update the Ruby PetStore API client undersamples/client/petstore/ruby
(For Windows, the batch files can be found underbin\windows
folder) - Run the tests in the sample folder, e.g. in
samples/client/petstore/ruby
, runmvn integration-test -rf :RubyPetstoreClientTests
. (some languages may not contain unit testing for Petstore and we're looking for contribution from the community to implement those tests) - Finally, git commit the updated samples files:
git commit -a
(git add -A
if added files with new test cases)
To start the CI tests, you can run mvn verify -Psamples
(assuming you've all the required tools installed to run tests for different languages) or you can leverage http://travis-ci.org to run the CI tests by adding your own Swagger-Codegen repository.
- Smaller changes are easier to review
- [Optional] For bug fixes, provide a OpenAPI Spec to repeat the issue so that the reviewer can use it to confirm the fix
- Add test case(s) to cover the change
- Document the fix in the code to make the code more readable
- Make sure test cases passed after the change (one way is to leverage https://travis-ci.org/ to run the CI tests)