Swaggy C is a builder for OpenAPI Generator-generated API clients in multiple technology stacks.
It provides utility targets for generating the API clients, building, testing, and publishing the artifacts, from an OpenAPI spec in one go.
Have a look at Swaggy Jenkins as an example project that was built using Swaggy C.
- Copy
src/Makefile-swaggy-cto be theMakefileof your project: curl https://raw.githubusercontent.com/cliffano/swaggy-c/main/src/Makefile-swaggy-c -o Makefile - Create configuration file
swaggy-c.ymlwith properties described in Configuration section - Run the available
Makefiletargets described in Usage section
Create Swaggy C configuration file called swaggy-c.yml with contains the following properties:
| Property | Description | Example |
|---|---|---|
| spec_uri | File path or URL where the OpenAPI specification is located | spec/some-app.yaml or https://some-app.com/some-app.yaml |
| version | Version of the application using Swaggy C | 1.2.3 |
| contact.name | Contact name to be amended to the OpenAPI specification | John Citizen |
| contact.url | Contact URL to be amended to the OpenAPI specification | https://some-app.com |
| contact.email | Contact email to be amended to the OpenAPI specification | johnc@some-app.com |
| scm.git_user | Git user/org name to be amended to the generated OpenAPI Generator configuration | johncitizen |
| scm.git_repo | Git repo name to be amended to the generated OpenAPI Generator configuration | some-app |
| base_dir.github_actions | Absolute path where the application base directory is located within GitHub Actions runner, use this by setting GITHUB_ACTIONS environment variable | /home/runner/work/some-app/some-app |
| base_dir.local | Absolute path where the application base directory is located within your local environment, use this when no environment variable specified | /Users/some-user/some-path/some-app |
| base_dir.custom | Absolute path where the application base directory is any custom directory, use this by setting CUSTOM environment variable | /Users/some-user/some-path/some-app |
The following targets are available:
| Target | Description |
|---|---|
| ci | CI target to be executed by CI/CD tool |
| stage | Ensure stage directory exists |
| clean | Remove all generated API clients code |
| deps | Retrieve the OpenAPI Generator Docker image and npm modules |
| init-spec | Initialise OpenAPI specification from either a local file path or a remote URL |
| init-langs-config | Initialise empty configuration file for all languages |
| update-to-latest | Update Makefile to the latest version on origin's main branch |
| update-to-version | Update Makefile to the version defined in TARGET_SWAGGY_C_VERSION parameter |
| generate | Alias for generate-all target |
| generate-all | Generate API clients for all languages, this is separate from generate-primary target in order to reduce the build time when processing primary languages |
| generate-primary | Generate API clients for primary languages only |
| build- | API clients building targets for primary languages |
| test- | API clients testing targets for primary languages |
| publish- | API clients package publishing targets for primary languages |
| doc | Alias for doc-latest target |
| doc-latest | Generate API documentation locally as the latest version |
| doc-version | Generate API documentation locally as the application's version |
| doc-publish | Publish documentation via GitHub Pages |
To 4.x.x:
- Revert all references of python-nextgen to python
To 2.x.x:
- Copy clients/python/conf.json to clients/python-nextgen/conf.json
- Rename all references of python to python-nextgen in GitHub Actions assets
Related Project:
- OpenAPI Clients Factory - A project to produce OpenAPI-based clients using OpenAPI Generator