This is the main generator responsible for generating the OpenFGA SDKs from the OpenFGA OpenAPIv2 Document.
OpenFGA is an open source Fine-Grained Authorization solution inspired by Google's Zanzibar paper. It was created by the FGA team at Auth0 based on Auth0 Fine-Grained Authorization (FGA), available under a permissive license (Apache-2) and welcomes community contributions.
OpenFGA is designed to make it easy for application builders to model their permission layer, and to add and integrate fine-grained authorization into their applications. OpenFGA’s design is optimized for reliability and low latency at a high scale.
- OpenFGA Documentation
- OpenFGA API Documentation
- OpenFGA Community
- Zanzibar Academy
- Google's Zanzibar Paper (2019)
| Language | GitHub | Package Manager |
|---|---|---|
| Javascript | openfga/js-sdk |  |
| Go | openfga/go-sdk |  |
| .NET | openfga/dotnet-sdk |  |
| Python | openfga/python-sdk |  |
| Java | openfga/java-sdk |  |
- Git
- Docker
- Make (Optional, but makes things much easier)
- curl
- Bash
- sed
- Clone this repo:
git clone [email protected]:openfga/sdk-generator.git- Clone existing SDKs into the clients directory
git clone [email protected]:openfga/go-sdk.git clients/fga-go-sdk
git clone [email protected]:openfga/js-sdk.git clients/fga-js-sdk
git clone [email protected]:openfga/dotnet-sdk.git clients/fga-dotnet-sdk
git clone [email protected]:openfga/python-sdk.git clients/fga-python-sdk
git clone [email protected]:openfga/java-sdk.git clients/fga-java-sdk- Build and test the client sdks
makeThere is a helpful script to setup a new SDK
make setup-new-sdk- It will ask you for a an SDK ID, use something like: go, js, dotnet, java, etc...
- It will ask you for a valid generator
- Then in will initialize all the files, you will need to add the configuration specific to that sdk
- Now you can run
make build-client-${SDK_ID}to generate the SDK
- Create config dir in:
config/clients/{lang}/. It should include:CHANGELOG.md: To be updated as new releases are generatedgenerator.txt: the name of the generator to use. Must be a valid generatorconfig.overrides.json: Custom config for this generator + overrides to the common config inconfig/common/config.base.json.openapi-generator-ignore: Any files that the generator should ignore and not builttemplate-source: Newer SDKs should have this to mark what commit of the generator we branched offtemplate/directoryLICENSE: Apache-2.0 License.github/workflows/main.yml: Any CI checks that need to run- The following files, each with the relevant section (look at the JS template for an example):
README_installation.mustacheREADME_initializing.mustacheREADME_calling_api.mustacheREADME_api_endpoints.mustacheREADME_models.mustacheREADME_license_disclaimer.mustacheREADME_custom_badges.mustache(optional, any custom badges for this specific SDK)gitignore_custom.mustache(optional, any custom ignores for this specific SDK)NOTICE_details.mustache(optional, see Updating the Notice files)
- custom files according to the generator
- Update the
Makefile.- add a target for the new sdk
.PHONY: build-client-{{LANG}}
build-client-{{LANG}}:
make build-client sdk_language={{LANG}} tmpdir=${TMP_DIR}
# ... any other custom build steps ...- add it as a dependency to the
build-all-clients
.PHONY: build-all-clients
build-all-clients: build-client-js build-client-go ... build-client-{{LANG}}- add a target for the new sdk's tests that depend on the build target
.PHONY: test-client-{{LANG}}
test-client-{{LANG}}: build-client-{{LANG}}
# ... any custom test code ...- add it as a dependency to the
test-all-clients
.PHONY: test-all-clients
test-all-clients: test-client-js test-client-go ... test-client-{{LANG}}Note: Try to ensure that the SDK is built through container files so that other contributors would not need to set up the full language framework/toolchain whenever they need to contribute. Checkout the go sdk build steps as an example.
1- Ensure that fossaComplianceNoticeId has been set in each SDK's config overrides.
2- Run make update-fossa-reports
Once the SDK is ready, you need to:
- Create a repo under the openfga github org. Call it:
${SDK_ID}-sdk - Add it to the generator's test and deploy actions
- Add any necessary secrets to the generator's repo on github (and document them in the readme)
Once the SDK is ready, you need to:
- Setup Snyk, and ensure no security issues are present
- Setup Fossa, and ensure no compliance issues are present
- Request a review from the team
Note: Semgrep will be automatically enabled - there is nothing you need to do for that.
| Key | Comment |
|---|---|
FOSSA_API_KEY |
FOSSA API Key |
SNYK_TOKEN |
Snyk API Key |
Please review the Contributing Guidelines before sending a PR or opening an issue.
In addition, we ask that the SDKs:
-
be generated from the openapiv2 swagger document using the sdk-generator.
-
have roughly the same consistent interface for configuration, such as JS, GoLang, .NET, Python and Java SDKs.
-
support the same features with other existing SDKs, including: Retries, Error Handling, .
-
have a base set of functional tests.
-
have no tests that talk to an external service (external calls should be disallowed and mocked).
-
have building & publishing automated through GitHub actions.
-
be created and modified through pull requests to this sdk-generator repository instead of individual repositories. Most of the code will be in mustache files that will end up generating the resulting SDK for the appropriate language.
This project is licensed under the Apache-2.0 license. See the LICENSE file for more info.
The template files in this repo are based on the original files from OpenAPI Generator.