Getting Started with OpenAPI Specification
In this guide we will generate Python and Java SDKs from an example OpenAPI Specification hosted at a fake endpoint.
Konfig's CLI requires Node 14+ to be setup on your machine.
1. Install konfig-cli
Run npm install -g konfig-cli or yarn global add konfig-cli to install Konfig's CLI.
2. Create a directory and cd into it.
3. Import your OpenAPI Specification (OAS)
In this example our OAS is hosted at https://api.petstore.com/petstore.yaml so
we use the wget utility to download it (note that this is not a real
endpoint). If your OAS is already locally available, you can simply copy it into your directory.
4. Setup your SDK directory
Run konfig init to initialize your directory with the necessary files to
generate SDKs. You will be asked onboarding questions to bootstrap your
configuration.
After you complete the onboarding questions, you will
see should have two files konfig.yaml and petstore.yaml in your directory.
konfig init will also setup other miscellaneous files for linting and VSCode.
The konfig.yaml configures what languages to generate SDKs for and how to generate them.
Each generator has a version field to specify the version of the SDK to
generate. We recommend using semantic versioning.
An outputDirectory to specify the subpath relative to konfig.yaml that the SDK should be copied to.
And git field to configure the userId and repoId of where the SDKs will be version controlled on GitHub.
Other configurations are language-specific that change things like the package name or top-level class name used when generating the SDKs.
5. Generate SDKs
Run konfig generate to generate SDKs. In the background konfig
will pick up your konfig.yaml along with your OAS and make a request to
generate SDKs (this can take a minute or two).
Once generation is complete, you will see two new directories containing your Python and TypeScript SDKs.
1. Install konfig-cli
Run npm install -g konfig-cli or yarn global add konfig-cli to install Konfig's CLI.
2. Create a directory and cd into it.
3. Import your OpenAPI Specification (OAS)
In this example our OAS is hosted at https://api.petstore.com/petstore.yaml so
we use the wget utility to download it (note that this is not a real
endpoint). If your OAS is already locally available, you can simply copy it into your directory.
4. Setup your SDK directory
Run konfig init to initialize your directory with the necessary files to
generate SDKs. You will be asked onboarding questions to bootstrap your
configuration.
After you complete the onboarding questions, you will
see should have two files konfig.yaml and petstore.yaml in your directory.
konfig init will also setup other miscellaneous files for linting and VSCode.
The konfig.yaml configures what languages to generate SDKs for and how to generate them.
Each generator has a version field to specify the version of the SDK to
generate. We recommend using semantic versioning.
An outputDirectory to specify the subpath relative to konfig.yaml that the SDK should be copied to.
And git field to configure the userId and repoId of where the SDKs will be version controlled on GitHub.
Other configurations are language-specific that change things like the package name or top-level class name used when generating the SDKs.
5. Generate SDKs
Run konfig generate to generate SDKs. In the background konfig
will pick up your konfig.yaml along with your OAS and make a request to
generate SDKs (this can take a minute or two).
Once generation is complete, you will see two new directories containing your Python and TypeScript SDKs.
Congrats 🎉🎉🎉🎉
You have successfully generated your first SDKs. Next you can test and publish
your SDKs which is also made easy by Konfig using konfig test and konfig publish.
When doing this on a real API you most likely will need to make modifications to your OAS to generate high quality SDKs. Konfig also makes this easy through its lint and fix utilities. You also probably want to setup Continuous Deployment through GitHub Action or polling. Sometimes its also necessary to add business logic in the SDKs which are also made easy by konfig through its native support for customization.
Interested?
If you are interested in generating SDKs with Konfig we would love to setup a time to talk. In the call we will learn about your particular requirements and answer any questions you might have. Typically it only takes a couple hours to get high quality SDKs and documentation after a conversation.