API Documentation

[robosats]

API Documentation

[zx9r]

Fixing incorrect link for currency numbers file:

https://github.com/Reckless-Satoshi/robosats/blob/main/frontend/static/assets/currencies.json

[ShatteredBunny]

What about adding Swagger/OpenAPI for documentation? Main benefits:

• Frontend code could be generated including types
• E.g. SwaggerUI would provide an up to date and interactive documentation

[ShatteredBunny]

I've also done a little research, django seems to be able to generate OpenAPI schemas, maybe that is good enough: https://www.django-rest-framework.org/topics/documenting-your-api/
So we could just add SwaggerUI to replace this issue (code as documentation, no need to update docs manually)

As mentioned in the drf-yasg readme, drf-spectacular uses OpenAPI 3.0 instead of 2.0 and is also actively maintained, I think this would be the best choice if we want something more powerful
drf-spectacular would allow to add annotations describing the endpoint (description, query parameters, optional or required etc.), I don't know if this is possible with plain django restframework.
The goal is that code for API calls could be generated including all parameters and types, e.g. using openapi-generator-cli and axios HTTP client
So the API cannot be used in a wrong way by accident, type errors in the frontend when the api changed (after converting components to ts) etc.

[ShatteredBunny]

I believe it is not as high priority as other rewarded tasks

Agreed, it's only for convenient development

Possible steps for this task:

Backend

• Expose OpenAPI definition endpoint (JSON). If it is possible to do everything using Django restframework, that's best; otherwise e.g. drf-spectacular could be used
• Add UI replacing this issue, e.g. SwaggerUI
• Make sure the API definition is complete, in particular that all request and response types and parameters are available and correct. If possible this is auto-generated, but maybe metadata in form of annotations is necessary. Also add the descriptions from this issue

Frontend

• Generate TypeScript code from OpenAPI definition endpoint and document how to do it
• Refactor frontend code to use generated code

[Reckless-Satoshi]

I see all of these points are quite a bit of work. However, the generation of TypeScript code for the frontend and refactoring puts us one step closer to following best practices and can be seen as a prerequisite towards RoboSats PRO frontend.

Documenting the API task as defined by @ShatteredBunny above is ⚡ rewarded with 300K Sats ⚡ Send a comment if you want to be assigned.

[ShatteredBunny]

Btw, @ShatteredBunny, don't want to nab this issue from you. If you have already started and were planning to do this anyway, you can take this up :)

Feel free to do it, I intentionally did not get me assigned :)

[Reckless-Satoshi]

Swagger/OpenAPI for documentation?

I have no experience myself with these and what are the benefits over plain Django Restframework. I've done a little research and looks like a good idea. Maybe the best tool for this is drf-yasg ? It looks straightforward, what do you think? We could create a rewarded task for it.

[Reckless-Satoshi]

Would you make short bullet-point list of what this task might look like? Just to get a rough idea how much work implementing this would be.

I believe it is not as high priority as other rewarded tasks, but we could only put into it 100K to 200K Sats as a bit of an incentive.

[redphix]

Hey I want to take a dig at this! One question though.

Generate TypeScript code from OpenAPI definition endpoint and document how to do it

Does this mean automatically fetching all routes and auto defining handlers/functions? Also auto defining TS models for request/response schemas?

[redphix]

Or I feel like we can use a client-library generator (there are a few of them available) that would create a library from the openapi spec. Maybe this could be incorporated in the build pipeline? @Reckless-Satoshi. That could be a bit of a stretch I guess, but need to see how viable and useful that would be.

[ShatteredBunny]

Generate TypeScript code from OpenAPI definition endpoint and document how to do it

Does this mean automatically fetching all routes and auto defining handlers/functions? Also auto defining TS models for request/response schemas?

My idea was that you start the backend with openapi endpoint and then run the generation command which fetches the definition and generates the code

I already played a bit around, you can have a look at my fork, branch api-docs. In the package.json is a generation command. Code is generated and I tested usage with the stealth invoice endpoint. The definitions are incomplete though and I don't know what best practices in python/django are...

[ShatteredBunny]

create a library from the openapi spec

I'd like it but then it belongs into another repository?

[redphix]

I'd like it but then it belongs into another repository?

Yes. Was thinking the same, but do we want it is the question? Definitely makes it easier for people writing their own frontends bots to quickly use the library. Thoughts @Reckless-Satoshi ?

edit: on second thoughts though, it seems a little overkill. A REST api with proper openapi spec seems to be more than enough.

[redphix]

I already played a bit around, you can have a look at my fork, branch api-docs. In the package.json is a generation command. Code is generated and I tested usage with the stealth invoice endpoint. The definitions are incomplete though and I don't know what best practices in python/django are...

Nice! There should be a way to get the yaml without running the backend I guess right? After all it's all static, so it should be plausible(?)

[ShatteredBunny]

Nice! There should be a way to get the yaml without running the backend I guess right? After all it's all static, so it should be plausible(?)

Theoretically, not sure. But is this necessary? Once in production one can also get the yaml from there

[ShatteredBunny]

edit: on second thoughts though, it seems a little overkill. A REST api with proper openapi spec seems to be more than enough.

Agreed, and it's only ts, useless for other programming languages

[redphix]

But is this necessary? Once in production one can also get the yaml from there

Yes. you don't want to depend on production which is an external source. Say you were developing a new feature that made you change some endpoints or add new endpoints, that certainly won't be available on production. Idk, the extra step of "run the django server before running 'generate-api'" seems to be a little "coupled". We should make it such that we can build the frontend in a static way. i.e everything required to build it is available as a file somewhere. But maybe that's not possible to do statically, and there will be this intermediary step every time - in which case It's just a pipe dream I am having :P

[redphix]

Btw, @ShatteredBunny, don't want to nab this issue from you. If you have already started and were planning to do this anyway, you can take this up :)

[ShatteredBunny]

Yes. you don't want to depend on production which is an external source. Say you were developing a new feature that made you change some endpoints or add new endpoints, that certainly won't be available on production

If you're changing the API you must run it anyway to test it, if you're developing another client, production would be fine
I don't see a great benefit but if you can find something, why not