Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Added an example to get the contracts by trait #1699

Closed
wants to merge 7 commits into from
Closed
Show file tree
Hide file tree
Changes from 1 commit
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
21 changes: 21 additions & 0 deletions docs/entities/contracts/contracts-by-trait.example.json
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The .example.json files are used mainly for response bodies... I think in this case the example should be a string on the openapi.yaml file

Original file line number Diff line number Diff line change
@@ -0,0 +1,21 @@
{
"functions": [
{
"access": "read_only",
"args": [],
"name": "get-total-supply",
"outputs": {
"type": {
"response": {
"ok": "uint128",
"error": "uint128"
}
}
}
}
],
"variables": [],
"maps": [],
"fungible_tokens": [],
"non_fungible_tokens": []
}
9 changes: 9 additions & 0 deletions docs/openapi.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -976,6 +976,15 @@ paths:
tags:
- Smart Contracts
operationId: get_contracts_by_trait
requestBody:
description: Trait Application Binary Interface(ABI) in the JSON format
required: true
content:
application/json:
schema:
type: string
example:
$ref: ./entities/contracts/contracts-by-trait.example.json
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm not sure if this is correct. The endpoint is GET /extended/v1/contract/by_trait?trait_abi=<value> where <value> is the URI encoded JSON-stringified ABI object.

So rather than requestBody here (which I think is mostly for POST requests), seems like it should be something like:

parameters:
  - in: query
    name: by_trait
    content:
      application/json:
        schema:
          type: object
          properties: ...

This suggestion was just from a cursory look over how to specify json in a query param -- you should double check if this is actually the expected approach.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

If OpenAPI schema doesn't actually allow specifying a JSON-stringified query param, then you may just have to specify a string query param and document that it needs to be the JSON-stringified object, e.g.:

parameters:
  - in: query
    name: by_trait
    description: JSON stringified ABI object e.g. `JSON.stringify(abi)`
    schema:
      type: string

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I tried to add the following code to the yaml file, but I don't see any change in the output. May I know if this is the right way to add parameters to the OpenAPI.yaml?

parameters:
        - name: trait_abi
          in: query
          description: JSON stringified ABI object e.g. `JSON.stringify(abi)`.
          required: true
           schema:  # The request schema
              type: object  # JSON object type
              properties:
                functions:
                  type: array
                  items:
                    type: object
                    properties:
                      access:
                        type: string
                      args:
                        type: array
                        items: {}
                      name:
                        type: string
                      outputs:
                        type: object
                        properties:
                          type:
                            type: object
                            properties:
                              response:
                                type: object
                                properties:
                                  ok:
                                    type: string
                                    format: uint128
                                  error:
                                    type: string
                                    format: uint128
                variables:
                  type: array
                  items: {}
                maps:
                  type: array
                  items: {}
                fungible_tokens:
                  type: array
                  items: {}
                non_fungible_tokens:
                  type: array
                  items: {} ```
     

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

If the above approach is incorrect, I will go ahead with this commit.

Copy link
Member

@zone117x zone117x Jul 27, 2023

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The OpenAPI 3.0 spec on object parameters is here: https://swagger.io/specification/v3/#parameter-object-examples

It looks like the first example I gave may be correct. I don't think you should be trying to define the entire possible ABI object here though, you're going to end up having to specify a large complex enum of clarity types. It seems fine to me if the spec simply states a string and just explain the JSON encoded abi in the description.

responses:
200:
description: List of contracts implement given trait
Expand Down
Loading