Question: is the spec compatible with OpenAPI?

[AF-cgi]

I figured out that the current openapi.yaml file hasn't a valid Open API spec. Is this correct? This will be hard to use some code generation tools to build a network layer based on your specs.

[grace-figma]

Hi, do you have additional details? openapi.yaml should be valid Open API, and looks valid to me.

[nfirex]

@grace-figma
Hello!

Do you have any good client generators for kotlin?

I tried this one:
https://github.com/OpenAPITools/openapi-generator/blob/master/modules/openapi-generator-gradle-plugin/README.adoc

And online swagger:
https://editor-next.swagger.io/

But they both generates invalid retrofit clients:
For example - method getMe() from User Api returns nothing:

[AF-cgi]

@grace-figma Hello!

Do you have any good client generators for kotlin?

I tried that one: https://github.com/OpenAPITools/openapi-generator/blob/master/modules/openapi-generator-gradle-plugin/README.adoc

And online swagger: https://editor-next.swagger.io/

But they both generates invalid retrofit clients: For example - method getMe() from User Api return nothing:

That was also my issue. I will try the Swagger Codegen, because the Swagger UI is the only tool that returns valid for the current specification.

[nfirex]

Some new info.

I tried manually change schema and build minor parts. And faced with parsing errors. That means that a lot of fields checked as required, but API don't return it:
Exception in thread "main" com.squareup.moshi.JsonDataException: Required value 'shapeType' missing at $.document.children[0].children[1] at com.squareup.moshi.internal.Util.missingProperty(Util.java:660) at com.squareup.moshi.kotlin.reflect.KotlinJsonAdapter.fromJson(KotlinJsonAdapter.kt:105) at com.squareup.moshi.internal.NullSafeJsonAdapter.fromJson(NullSafeJsonAdapter.java:41) at com.squareup.moshi.CollectionJsonAdapter.fromJson(CollectionJsonAdapter.java:81) at com.squareup.moshi.CollectionJsonAdapter$2.fromJson(CollectionJsonAdapter.java:55) at com.squareup.moshi.internal.NullSafeJsonAdapter.fromJson(NullSafeJsonAdapter.java:41) at com.squareup.moshi.kotlin.reflect.KotlinJsonAdapter.fromJson(KotlinJsonAdapter.kt:86) at com.squareup.moshi.internal.NullSafeJsonAdapter.fromJson(NullSafeJsonAdapter.java:41) at com.squareup.moshi.CollectionJsonAdapter.fromJson(CollectionJsonAdapter.java:81) at com.squareup.moshi.CollectionJsonAdapter$2.fromJson(CollectionJsonAdapter.java:55) at com.squareup.moshi.internal.NullSafeJsonAdapter.fromJson(NullSafeJsonAdapter.java:41) at com.squareup.moshi.kotlin.reflect.KotlinJsonAdapter.fromJson(KotlinJsonAdapter.kt:86) at com.squareup.moshi.internal.NullSafeJsonAdapter.fromJson(NullSafeJsonAdapter.java:41) at com.squareup.moshi.kotlin.reflect.KotlinJsonAdapter.fromJson(KotlinJsonAdapter.kt:86) at com.squareup.moshi.internal.NullSafeJsonAdapter.fromJson(NullSafeJsonAdapter.java:41) at com.squareup.moshi.JsonAdapter.fromJson(JsonAdapter.java:70)

[nfirex]

Exception in thread "main" com.squareup.moshi.JsonDataException: Required value 'shapeType' missing at $.document.children[0].children[1] at

response:

{
"document": {
"id": "0:0",
"name": "Document",
"type": "DOCUMENT",
"scrollBehavior": "SCROLLS",
"children": [
{
"id": "0:1",
"name": "Page 1",
"type": "CANVAS",
"scrollBehavior": "SCROLLS",
"children": [
{
"id": "2:2",
"name": "Rectangle 1",
"type": "RECTANGLE",
"scrollBehavior": "SCROLLS",
"blendMode": "PASS_THROUGH",
"fills": [
{
"blendMode": "NORMAL",
"type": "SOLID",
"color": {
"r": 0.8509804010391235,
"g": 0.8509804010391235,
"b": 0.8509804010391235,
"a": 1
}
}
],
"strokes": [],
"strokeWeight": 1,
"strokeAlign": "INSIDE",
"absoluteBoundingBox": {
"x": -364,
"y": 38,
"width": 441,
"height": 268
},
"absoluteRenderBounds": {
"x": -364,
"y": 38,
"width": 441,
"height": 268
},
"constraints": {
"vertical": "TOP",
"horizontal": "LEFT"
},
"effects": [],
"interactions": []
}
],
"backgroundColor": {
"r": 0.9607843160629272,
"g": 0.9607843160629272,
"b": 0.9607843160629272,
"a": 1
},
"prototypeStartNodeID": null,
"flowStartingPoints": [],
"prototypeDevice": {
"type": "NONE",
"rotation": "NONE"
}
}
]
},
"components": {},
"componentSets": {},
"schemaVersion": 0,
"styles": {},
"name": "Untitled",
"lastModified": "2024-12-19T17:57:46Z",
"thumbnailUrl": "https://s3-alpha.figma.com/thumbnails/0fb2e4ba-61c5-480a-b913-8e54fe2f2abd?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIAQ4GOSFWCZ5JER5WN%2F20241219%2Fus-west-2%2Fs3%2Faws4_request&X-Amz-Date=20241219T000000Z&X-Amz-Expires=604800&X-Amz-SignedHeaders=host&X-Amz-Signature=2dd35ea0f8e4958ffa5732efc4d51f158d1788fa6618d1a861da54c3d0c12949",
"version": "2163888010403840939",
"role": "owner",
"editorType": "figma",
"linkAccess": "inherit"
}

[grace-figma]

🤔 thanks for the additional info, I'll look into it

[AF-cgi]

I get the following issue by using version 0.22.0 with swift-openapi-generator.

[jefflee-figma]

Thanks for the report here...we admittedly haven't done a huge amount of testing this OpenAPI spec outside of TypeScript. For what it's worth, the spec seems to validate properly in a 3.1 validator, and the openapi-typescript generates what we think is a pretty high-fidelity schema (example).

The schema does make heavy use of polymorphic types (e.g. anyOf and oneOf type descriptors), which are easily handled in TypeScript using a | type union operator. I wonder if some code generators aren't able to handle this gracefully, or if we are missing some annotation such as descriminator for facilitating that.

I think @nfirex's example about re: a missing shapeType property is a case in point: shapeType only appears in nodes of type SHAPE_WITH_TEXT. There is no SHAPE_WITH_TEXT in the example JSON, which means the generated SDK is misapplying object schemas, possibly because it doesn't know how to pick which one to use.

At any rate, we'll be looking into this, but in the mean time, we'd appreciate any advice from the community for tweaking the structure of the schema so it supports a wider range of tools.

[AF-cgi]

I have some updates to that topic. I figured out what happens with my code generator. My code generator doesn't support - type: "null" of oneOf properties in object specification. Here is an example from #components/schemas:

VariableValue:
      description: The value for the variable. The value must match the variable's
        type. If setting to a variable alias, the alias must resolve to this
        type. If overriding a value, the value type must match the variable's
        type. If removing an overridden value, the value must be `null`.
      oneOf:
        - type: boolean
        - type: number
        - type: string
        - $ref: "#/components/schemas/RGB"
        - $ref: "#/components/schemas/RGBA"
        - $ref: "#/components/schemas/VariableAlias"
        - type: "null"

- type: "null" in oneOf is a valid option in OpenAPI specification. But my code generator doesn't support it yet. I've found a way to fix this for this code generator. So I close this question here, because it's not related to the specification here or an issue with it.