Sleekplan Logo
we run on Sleekplan

OpenAPI definition is not up to date and sometime invalid

As part of our integration process, we use the openAPI specificaton that was available [here](https://sleekplan.com/docs/api/#/) which link us to the following description [here](https://stoplight.io/api/v1/projects/sleekplan/sleekplan-api/nodes/reference/Sleekplan-API.yaml) 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](https://redocly.com/docs/cli/commands/lint) as follow ```bash 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 ```bash [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 ```bash [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](https://github.com/openapi-ts/openapi-typescript). I tryed to generate a client library which lead to weirds types like a `Record` wich usable. this is due to a missing attribute in the OpenAPI description when a free-form object is used see [here](https://swagger.io/docs/specification/data-models/dictionaries/) [IMAGE](https://storage.sleekplan.com/products/1/feedback/166746/comments/248874/53c4a548c712135cb174acc1c18d048d.jpg) In that case you need to add the `additionalProperties: true` so the end definition will be a `Record` which match the flexibility needed to this field. as reference, see : https://openapi-ts.pages.dev/advanced [IMAGE](https://storage.sleekplan.com/products/1/feedback/166746/comments/248874/c293b1210a0d16803a8e887b277549c4.jpg) 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: - https://jsonlint.com/ section about empty object and empty array representation [IMAGE](https://storage.sleekplan.com/products/1/feedback/166746/comments/248874/7ec7b691d790ddb78d850eed1f6b2572.jpg) - https://www.json.org/json-en.html the first schema that describe the json object representation. [IMAGE](https://storage.sleekplan.com/products/1/feedback/166746/comments/248874/3461ffb3b70dfd82a379597127846608.jpg) this kind of inconsistency is some how a major issue because all the openapi generator expect the right value to be returned and sometime could crash if something unexpected append. in the best case, the generated client will only throw an error and it would be on the client end to fix this issue. Please let me konw if i can help in any way. Best, Jeremy.