forked from hyperledger-cacti/cacti
-
Notifications
You must be signed in to change notification settings - Fork 0
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
build: add OpenAPI spec bundling, stop using URL references
**IMPORTANT:** From now on, if you are changing the OpenAPI specification of any given package within Cacti, please make sure to edit the template file instead of editing the openapi.json specific file directly because changes in the openapi.json file will be overwritten by the codegen script the next time you run it. This slight alteration in the development flow is the least intrusive solution I could find to resolving our issues with the release automation. This change enables us to have our openapi.json files work without having remote and URL references in them (which was a blocker issue for release automation). 1. The openapi.json files that we used to have are now called openapi.tpl.json where the tpl stands for template. Their content is equivalent to what openapi.json files used to have prior to this commit. 2. These template specs are fed into the bundler tool which then spits out the files which then are saved as openapi.json files. The big change is that these bundled versions are no longer containing any remote nor URL references, only local ones. 3. This means that we still get project-wide re-use of schema types from packages such as cactus-core-api, but we no longer suffer from the additional complexities of having to deal with remote and URL references. 4. The scirpt that performs the bundling is callable separately by executing this command ```sh yarn tools:bundle-open-api-tpl-files ``` 5. The `yarn tools:bundle-open-api-tpl-files` is also embedded as a warmup step of the larger `codegen` script so there is no need usually to call the bundling script separately. 6. The heavylifting in terms of bundling is done by the tooling script that can be found here: `tools/bundle-open-api-tpl-files.ts`. On a high level what it does is loop through existing `openapi.tpl.json` files throughout the project and then renders their bundled version next to it as `openapi.json` which then can be used by all of our tools as a self contained version of the template file which *does* still have the remote and URL references in it. More information on what URL and remote references are can be read here on the official OpenAPI website: https://swagger.io/docs/specification/using-ref/ Signed-off-by: Peter Somogyvari <[email protected]>
- Loading branch information
Showing
49 changed files
with
20,723 additions
and
574 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
235 changes: 235 additions & 0 deletions
235
...les/cactus-example-carbon-accounting-business-logic-plugin/src/main/json/openapi.tpl.json
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,235 @@ | ||
| { | ||
| "openapi": "3.0.3", | ||
| "info": { | ||
| "title": "Hyperledger Cactus Example - Carbon Accounting App", | ||
| "description": "Demonstrates how a business use case can be satisfied with Cactus when multiple distinct ledgers are involved.", | ||
| "version": "v2.0.0-alpha.2", | ||
| "license": { | ||
| "name": "Apache-2.0", | ||
| "url": "https://www.apache.org/licenses/LICENSE-2.0.html" | ||
| } | ||
| }, | ||
| "components": { | ||
| "schemas": { | ||
| "AuthzScope": { | ||
| "type": "string", | ||
| "enum": ["group:admin", "group:user"], | ||
| "x-enum-descriptions": [ | ||
| "Identities with the group:admin scope are administrators of the system.", | ||
| "Identities with the group:user scope are end users of the system who only have authorization to perform a limited set of actions." | ||
| ], | ||
| "x-enum-varnames": ["GroupAdmin", "GroupUser"] | ||
| }, | ||
| "AuthzJwtClaim": { | ||
| "description": "Stores global constants related to the authorization of the application. Specifically enumerates the claims to validate for as per RFC 7519, section 4.1. See: https://tools.ietf.org/html/rfc7519#section-4.1", | ||
| "type": "string", | ||
| "enum": ["Hyperledger Labs - Carbon Accounting Tool"], | ||
| "x-enum-descriptions": [ | ||
| "The \"iss\" (issuer) claim identifies the principal that issued the JWT. The processing of this claim is generally application specific. The \"iss\" value is a case-sensitive string containing a StringOrURI value. Use of this claim is OPTIONAL." | ||
| ], | ||
| "x-enum-varnames": ["iss"] | ||
| }, | ||
| "Checkpoint": { | ||
| "required": ["fromBlock", "votes"], | ||
| "properties": { | ||
| "fromBlock": { | ||
| "type": "integer", | ||
| "format": "uint32", | ||
| "nullable": false | ||
| }, | ||
| "votes": { | ||
| "type": "string", | ||
| "nullable": false, | ||
| "format": "uint96" | ||
| } | ||
| } | ||
| }, | ||
| "EnrollAdminInfo": { | ||
| "type": "string", | ||
| "enum": [ | ||
| "Successfully enrolled admin user and imported it into the wallet", | ||
| "ORG ADMIN REGISTERED" | ||
| ], | ||
| "x-enum-varnames": [ | ||
| "SUCCESSFULLY_ENROLLED_ADMIN", | ||
| "ORG_ADMIN_REGISTERED" | ||
| ] | ||
| }, | ||
| "EnrollAdminV1Request": { | ||
| "type": "object", | ||
| "required": ["orgName"], | ||
| "properties": { | ||
| "orgName": { | ||
| "type": "string", | ||
| "minLength": 1, | ||
| "maxLength": 1024 | ||
| } | ||
| } | ||
| }, | ||
| "EnrollAdminV1Response": { | ||
| "type": "object", | ||
| "required": ["info", "orgName", "msp", "caName"], | ||
| "properties": { | ||
| "info": { | ||
| "type": "string", | ||
| "minLength": 1, | ||
| "maxLength": 2048, | ||
| "nullable": false | ||
| }, | ||
| "orgName": { | ||
| "type": "string", | ||
| "minLength": 1, | ||
| "maxLength": 2048, | ||
| "nullable": false | ||
| }, | ||
| "msp": { | ||
| "type": "string", | ||
| "minLength": 1, | ||
| "maxLength": 2048, | ||
| "nullable": false | ||
| }, | ||
| "caName": { | ||
| "type": "string", | ||
| "minLength": 1, | ||
| "maxLength": 2048, | ||
| "nullable": false | ||
| }, | ||
| "identityId": { | ||
| "description": "The key under which the identity created will be persisted to the keychain for later retrieval.", | ||
| "type": "string", | ||
| "minLength": 1, | ||
| "maxLength": 2048, | ||
| "nullable": false | ||
| } | ||
| } | ||
| }, | ||
| "DaoTokenGetAllowanceRequest": { | ||
| "type": "object", | ||
| "required": ["account", "spender"], | ||
| "properties": { | ||
| "account": { | ||
| "description": "The address of the account holding the funds", | ||
| "type": "string", | ||
| "minLength": 40, | ||
| "maxLength": 42 | ||
| }, | ||
| "spender": { | ||
| "description": "The address of the account spending the funds", | ||
| "type": "string", | ||
| "minLength": 40, | ||
| "maxLength": 42 | ||
| } | ||
| } | ||
| }, | ||
| "DaoTokenGetAllowanceResponse": { | ||
| "type": "object", | ||
| "required": ["allowance"], | ||
| "properties": { | ||
| "allowance": { | ||
| "type": "integer", | ||
| "nullable": false, | ||
| "description": "The number of tokens approved" | ||
| } | ||
| } | ||
| }, | ||
| "DaoTokenGetAllowanceNotFoundResponse": { | ||
| "type": "object", | ||
| "required": ["accountFound", "spenderFound"], | ||
| "properties": { | ||
| "accountFound": { | ||
| "type": "boolean", | ||
| "nullable": false, | ||
| "description": "Indicates whether the account was found or not." | ||
| }, | ||
| "spenderFound": { | ||
| "type": "boolean", | ||
| "nullable": false, | ||
| "description": "Indicates whether the spender was found or not." | ||
| } | ||
| } | ||
| } | ||
| } | ||
| }, | ||
| "paths": { | ||
| "/api/v1/utilityemissionchannel/registerEnroll/admin": { | ||
| "post": { | ||
| "operationId": "enrollAdminV1", | ||
| "summary": "Registers an admin account within the Fabric organization specified.", | ||
| "x-hyperledger-cacti": { | ||
| "authz": { | ||
| "isProtected": true, | ||
| "requiredRoles": ["group:admin"] | ||
| }, | ||
| "http": { | ||
| "verbLowerCase": "post", | ||
| "path": "/api/v1/utilityemissionchannel/registerEnroll/admin" | ||
| } | ||
| }, | ||
| "requestBody": { | ||
| "content": { | ||
| "application/json": { | ||
| "schema": { | ||
| "$ref": "#/components/schemas/EnrollAdminV1Request" | ||
| } | ||
| } | ||
| } | ||
| }, | ||
| "responses": { | ||
| "200": { | ||
| "description": "OK", | ||
| "content": { | ||
| "application/json": { | ||
| "schema": { | ||
| "$ref": "#/components/schemas/EnrollAdminV1Response" | ||
| } | ||
| } | ||
| } | ||
| } | ||
| } | ||
| } | ||
| }, | ||
| "/api/v1/plugins/@hyperledger/cactus-example-carbon-accounting-backend/dao-token/get-allowance": { | ||
| "post": { | ||
| "operationId": "daoTokenGetAllowanceV1", | ||
| "summary": "Get the number of tokens `spender` is approved to spend on behalf of `account`", | ||
| "x-hyperledger-cacti": { | ||
| "http": { | ||
| "verbLowerCase": "post", | ||
| "path": "/api/v1/plugins/@hyperledger/cactus-example-carbon-accounting-backend/dao-token/get-allowance" | ||
| } | ||
| }, | ||
| "requestBody": { | ||
| "content": { | ||
| "application/json": { | ||
| "schema": { | ||
| "$ref": "#/components/schemas/DaoTokenGetAllowanceRequest" | ||
| } | ||
| } | ||
| } | ||
| }, | ||
| "responses": { | ||
| "200": { | ||
| "description": "OK", | ||
| "content": { | ||
| "application/json": { | ||
| "schema": { | ||
| "$ref": "#/components/schemas/DaoTokenGetAllowanceResponse" | ||
| } | ||
| } | ||
| } | ||
| }, | ||
| "404": { | ||
| "description": "NOT_FOUND", | ||
| "content": { | ||
| "application/json": { | ||
| "schema": { | ||
| "$ref": "#/components/schemas/DaoTokenGetAllowanceNotFoundResponse" | ||
| } | ||
| } | ||
| } | ||
| } | ||
| } | ||
| } | ||
| } | ||
| } | ||
| } |
Oops, something went wrong.