New Suggestion
As part of our integration process, we use the openAPI specificaton that was available here which link us to the following description here
Using this description, i tried to use the openapi generator to create the sdk to use on my backend application but multiple problèmes occured.
First, I did a validation step using the redoc/cli lint tool as follow
docker run --rm -v $PWD:/spec redocly/cli lint https://stoplight.io/api/v1/projects/sleekplan/sleekplan-api/nodes/reference/Sleekplan-API.yaml
...
https://stoplight.io/api/v1/projects/sleekplan/sleekplan-api/nodes/reference/Sleekplan-API.yaml: validated in 400ms
❌ Validation failed with 3 errors and 32 warnings.
run `redocly lint --generate-ignore-file` to add all problems to the ignore file.
Thoses errors are mostly related with missing response definition
[6] https://stoplight.io/api/v1/projects/sleekplan/sleekplan-api/nodes/reference/Sleekplan-API.yaml:145:7 at #/paths/~1user/post/responses
Operation must have at least one `4XX` response.
143 | tags:
144 | - User
145 | responses:
| ^^^^^^^^^
146 | '200':
147 | description: OK
Warning was generated by the operation-4xx-response rule.
and some invalid name in object
[2] https://stoplight.io/api/v1/projects/sleekplan/sleekplan-api/nodes/reference/Sleekplan-API.yaml:3381:5 at #/components/securitySchemes/Bearer token
The map key in securitySchemes "Bearer token" does not match the regular expression "^[a-zA-Z0-9\.\-_]+$"
3379 | type: apiKey
3380 | in: query
3381 | Bearer token:
| ^^^^^^^^^^^^
3382 | type: http
3383 | scheme: bearer
Error was generated by the spec-components-invalid-map-name rule.
Which seems very simple to fix.
Then i tried to ignore the errors and warnings from the previous step and generate a Typescript lib using openapi-typescript.
I tryed to generate a client library which lead to weirds types like a Record<string, never>
wich usable. this is due to a missing attribute in the OpenAPI description when a free-form object is used see here
In that case you need to add the additionalProperties: true
so the end definition will be a Record<string, unknown>
which match the flexibility needed to
this field.
as reference, see : https://openapi-ts.pages.dev/advanced
I did all the necessary modifications on my end and try ro test the resulting library and i was surprised that sometime the Sleekplan-API return array
types inplace of object
types.
as part of the json specification, a non existing object must be returned as null
and an empty one as {}
see as reference:
Please let me konw if i can help in any way.
Best, Jeremy.