I tried to provide a CLI based on openapi specs with https://rest.sh, but it fails.
So I validated the specs from https://www.truenas.com/docs/files/scale_24.04.2_apiv2.json but validation doesn’t pass. I tried both at
Validation also fails from a local docker image, i.e.
docker run -v /path/to/scale_24.04.2_apiv2.json:/openapi.yaml --rm pythonopenapi/openapi-spec-validator /openapi.yaml
The validation of https://petstore3.swagger.io/api/v3/openapi.json instead passes.
Do you have any ideas before I start digging into it?
EDIT: openapi-generator fails early the generation of a simple client for any language, tried:
docker run --rm -v ${PWD}:/local openapitools/openapi-generator-cli generate -i https://www.truenas.com/docs/files/scale_24.04.2_apiv2.json -o /local/my-client -g go
I don’t think we’ve tested with these tools and would like to hear what the issues are.
I’d recommend testing against 24.10.BETA when it comes out Thursday.
That is the version where new bug fixes will go.
1 Like
Sticking with python validation on the current 24.10 nightly - just to avoid issues related to strong typing - I issued the following validation command
docker run \
-e SPECS_URL=https://www.truenas.com/docs/files/scale_24.10.nightly_apiv2.json \
--rm -it --entrypoint /bin/sh \
pythonopenapi/openapi-spec-validator \
-c 'mkdir /specs && wget -q -P /specs/ $SPECS_URL && openapi-spec-validator --schema 3.0 /specs/*.json'
The very first error shown seems
‘attrs_order’, ‘name’ do not match any of the regexes: ‘^x-’
At a first sight I’d say additional properties such as: _name_, _attrs_order_ should be renamed to something like x-attrs_order and x-name to conform to the OpenAPI extension naming convention.
BTW if I rename them, it complains for refs starting as #components instead of #/components, but fixing them it complains for issues related to other properties named with leading and trailing underscores, and possibly other that I’ve not inspected.
All in all it may be just a matter of custom attributes that were not properly formatted as OpenAPI extensions, plus some refs lacking the leading / (slash).
IMHO opening https://editor.swagger.io/ from a browser and importing https://www.truenas.com/docs/files/scale_24.10.nightly_apiv2.json from FIle|Import URL is straightfoward and can be very useful: it shows human-friendly errors in their context separating Structural from Semantic ones:
Probably the worst issue I’ve seen so far is DELETE operations cannot have a requestBody as I suppose the body is allowed (thought discouraged) just since OAS 3.1.
Changing APIs mid-release can be complex.
Can you put all your findings in a document: you can then include in a bug report or as a feature request.
Are your trying to automate TrueNAS config for your work? If you can include how its impacting your business, we’d like to know to help prioritize.
OK, no rush, I’m just experimenting with TrueNAS at home at the moment, also to gain confidence in case there is a business case in the future.
Just filed [NAS-130885] - iXsystems TrueNAS Jira.
Please note one of the issues - namely the lack of leading slash on refs - has been fixed in the meantime for 24.10-beta.1 by [NAS-128149] - iXsystems TrueNAS Jira.
So the ticket has been suddenly closed as not applicable: actually I read it as won’t fix, and it makes sense given that
this is not something we’re going to invest time into fixing. Websocket is the primary protocol by which we interact with our server app and we do not plan on extending or fixing the REST side. I would recommend using the websocket API. You may look at the https://github.com/truenas/api_client as a reference
As I understand it, the midclt client can also be built/run from the git repo GitHub - truenas/api_client recently spawned, even if for a 24.04.2 it works just on the /websocket path.
But it lacks a way to show/inspect all possible commands from a CLI perspective.
I was wondering if - apart from the official documentation versioned at websocket folder and websocket.hml -
there’s any static or runtime descriptor available, providing some sort of discoverability for the (DDP based) websocket api?
UPDATE: until I can find something better to maintainably generate a CLI with completion, I’m using this container image.
Wouldn’t it be nice if there was an official one?
