search

buildcore-io / core

Your web3 plug & play platform
https://www.buildcore.io
Apache License 2.0
4 stars 0 forks source link

Use OpenAPI docs instead of typedocs #2690

Closed Dr-Electron closed 5 months ago

Dr-Electron commented 11 months ago

Is your feature request related to a problem? Please describe.

Not sure about you, but I feel really confused by the current API docs. As a dev I want the OpenAPI spec to know how to do requests. And there are way better formats for those.

Describe the solution you'd like

I would recommend to create OpenAPI specs which can be displayed with docusaurus-plugin-openapi-docs

Describe alternatives you've considered

Leave it as is. But at least for GET/POST requests we should do this... Maybe we can even make it work for OTR requests somehow? We would need to remove some things, but I think that the plugin shows the needed info in a way better formatted way 🤔

adamunchained commented 11 months ago

Can the openapi definition be above the "@build-5/client" functions?

I.e. can we put it above function like this one: https://github.com/build-5/core/blob/9c2911ca608fe73fed777d1f71791b6b68871621/packages/client/src/https/datasets/space/SpaceDataset.ts#L22

Dr-Electron commented 11 months ago

Yes, that should work, i will create a PoC

adamunchained commented 11 months ago

great thanks!

Dr-Electron commented 10 months ago

Tools that could help us with this task: swagger-express and hapi-swagger

Dr-Electron commented 10 months ago

Although as we don't use express or hapi, this won't really work. As we use Axios, what about using openapi-client-axios which creates the client at runtime. Or if you prefer generated code, we could use the openapi-generator.

In both cases this would be a spec-first approach (which I actually prefer anyway 😆 )

adamunchained commented 10 months ago

This look all right. It also seems the openapi-client-axios is an active package too.

Dr-Electron commented 8 months ago

@adamunchained you should reassign this as this is something you have to work on. Create the API specs and then create code out of it for the SDK to build on

adamunchained commented 8 months ago

I agree. We have to immediate priorities we need to finish first:

Once we complete those we will will revisit these issues.

github-actions[bot] commented 6 months ago

Stale issue, closing!