Overview
Firstly this repository serves as a single point of entry for all language-variants of the Genesis API. All
variants can be found in the /server directory. The variant officially supported by Genesis Network,
the primary developers of Genesis is the NodeJS variant located in /server/nodejs. Deployment specifics can be found
in the README file relative to the desired variant (ie: /server/nodejs/README).
Secondly this repository allows users to generate various Genesis-API server and client stubs based on the provided OpenAPI spec in swagger.yaml. They can then complete the implementation of the business logic (if working on the server side) within that variant and issue a pull request- for more information see the Contributing section.
Generating API
To generate the API first download swagger-codegen and build it. After its built, create an alias:
alias swagger-codegen='java -jar [/path/to/built/swagger-codegen]/swagger-codegen/modules/swagger-codegen-cli/target/swagger-codegen-cli.jar'
Generating the JSON Spec
Anytime the root swagger.yaml is modified the JSON spec should be updated and copied into
swagger-ui/dist/swagger-spec.js as the value for the swaggerSpec var. Currently this is a manual process.
To regenerate the JSON API spec due to YAML changes (required for docs UI to be accurate):
swagger-codegen generate -i swagger.yaml -o ./generated-json -l swagger
The generated JSON can be deleted after its been copied to swagger-spec.js.
Generating Server Stubs
You can contribute to the genesis-api project by writing connectors for Genesis in different languages. Swagger-codegen can greatly reduce the time it takes to write connectors in other languages by generating a server-api stub in the desired language. To generate the Server stub use the command below replacing LANGUAGE with one of the supported SwaggerJS server values.
swagger-codegen generate -i swagger.yaml -o ./server/generated-server -l LANGUAGE
We encourage anyone who does this to submit a pull request to have their server API added to the official repo. Package your server API using folder names mirroring the swagger language name, ie: 'nodejs-server'. Client API's can also be submitted using the same format.
Generating the Client SDK
To quickly start communicating with an instance of the Genesis API server simply generate a client-side SDK in your preferred language. To generate the Client SDK use the command below replacing LANGUAGE with one of the supported SwaggerJS client values.
swagger-codegen generate -i swagger.yaml -o ./client/generated-client -l LANGUAGE
Alternatively (particularly for genesis)
We have added a script ./gen_client.sh to generate client inside /client folder.
Make sure your swagger-codegen-cli.jar is built from the same version/commit mentioned in /client/client/.swagger-codegen/VERSION.
Also update the /client/client/.swagger-codegen/VERSION if generated from a different version.
Arguments to pass to script
client language: typescript-angular
output directory: generated-client
path to swagger-codegen-cli: path to swagger-codegen-cli.jar
Contributing
This project is fully open source and welcomes pull requests at all levels. Simply fork the repository, apply your changes to the fork and then issue a pull request. Once reviewed the pull request will be integrated into master and (if warranted) released as a new official Genesis API version.
Credits
This project leverages the mega-awesome swagger-tools middleware which does most all the work.