Skip to content

Commit

Permalink
build: add OpenAPI spec bundling, stop using URL references
Browse files Browse the repository at this point in the history
**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
petermetz committed Jun 13, 2024
1 parent ec8123c commit 4a9ed0a
Show file tree
Hide file tree
Showing 49 changed files with 20,723 additions and 574 deletions.
8 changes: 6 additions & 2 deletions .cspell.json
Original file line number Diff line number Diff line change
Expand Up @@ -153,6 +153,8 @@
"protos",
"qscc",
"recoverupdateackmessage",
"redoc",
"redocly",
"rogpeppe",
"RUSTC",
"Rwset",
Expand All @@ -163,8 +165,8 @@
"shrn",
"Smonitor",
"socketio",
"Soroban",
"soroban",
"Soroban",
"SPDX",
"Splug",
"Sprintf",
Expand Down Expand Up @@ -193,7 +195,9 @@
"Xdai",
"xeipuuv"
],
"dictionaries": ["typescript,node,npm,go,rust"],
"dictionaries": [
"typescript,node,npm,go,rust"
],
"ignorePaths": [
"**/node_modules/**",
"**/build/**",
Expand Down
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"
}
}
}
}
}
}
}
}
}
Loading

0 comments on commit 4a9ed0a

Please sign in to comment.