Previously, we had explored how Aspida provides a way to integrate external Web APIs into your code in type-safe manner.
But writing down the complete type definition of an API by hand hardly seems very fun. Rather, we'd like it to be generated automatically.
openapi2aspida tools gives this functionality, as long as the API provides OpenAPI 3.0 or Swagger schema.
Generate Type Definition
Since you've followed instruction in previous post, you would have apis
directory, which this time openapi2aspida
expects it to be absent. So we need remove this before trying this tool.
$ rm -rf $REPO_ROOT/apis
Create aspida.config.js, Get JSON schema path
Run this to generate and pour packages into apis/
:
$ npx openapi2aspida --build
Try using
$ yarn run aspida-mock --build
> Property 'resHeaders' is missing in type '{ status: 200; resBody: { about: { description: string; title: string; locale: string; version: string; https: true; moderators: { id: number; username: string; avatar_template: string; name: string; title: string; }[]; admins: { ...; }[]; }; }; }' but required in type 'BaseResponse<{ about?: { description?: string; title?: string; locale?: string; version?: string; https?: boolean; moderators?: { id?: number; username?: string; avatar_template?: string; name?: string; title?: string; }[]; admins?: { ...; }[]; }; }, unknown, 200>'
Wow I thought I had tried to compile C++ abusing class templates here.
This error seems to occur because Discourse API doc (perhaps including OpenAPI schema). Discourse maintainers said so in the doc and the thread.
Let the linter explain before deep diving this ourselves:
$ yarn global add ibm-openapi-validator
$ curl -O https://docs.discourse.org/openapi.json
$ lint-openapi openapi.json | head -n 10
[Warning] No .validaterc file found. The validator will run in default mode.
To configure the validator, create a .validaterc file.
errors
Message : Parameters MUST have their data described by either `schema` or `content`.
Path : paths./c/{id}.json.get.parameters.0
Line : 296
$ lint-openapi openapi.json | wc -l
1318
Conclusion
We have tried Discourse API and found it lacked an OpenAPI-compiliant Schema. While openapi2aspida
doesn't seem to work very well in this situation, but if you are in a project where you have well-written OpenAPI schema, openapi2aspida
will be promising for your development.
Unfortunately, you wouldn't find so many projects with OpenAPI Schema out there at the moment. Yet we saw previously, we can start writing type definition by hand as necessary.
If you'll happen to be design a web API, you can contribute the OpenAPI ecosystem by starting it with writing OpenAPI Schema for the API. This might be encouraged from test-driven point of view.
Top comments (0)