search

SolomonDefi / solomon-monorepo

Monorepo containing core Solomon apps, services, libraries, and deploy config.
6 stars 4 forks source link

api document #206

Closed apolkingg8 closed 2 years ago

apolkingg8 commented 2 years ago

@kelvin-wong can you provide or generate a document like OpenAPI for api-dispute and api-evidence? It would be useful to do the e2e testing, thanks!

kelvin-wong commented 2 years ago

@apolkingg8 I have added API doc links in dev mode, you may provision your skaffold again. The dispute and evidence API doc links will be http://localhost:3000/docs and http://localhost:3010/docs respectively.

solomondefi-dev commented 2 years ago

Thanks!

apolkingg8 commented 2 years ago

I'll reopen this because something is missing in the document http://localhost:3000/docs. The param of POST /api/events is "No parameters", and it's the most important part of the doc.

@solomondefi-dev can you help on this? I just want a correct spec to implement e2e testings.

beefho67 commented 2 years ago

@solomondefi-dev @apolkingg8 This is blocking #161. Anything I can help with / work on the issue after I am back from Chinese New Year break?

solomondefi-dev commented 2 years ago

@apolkingg8 It's non-trivial to automatically create API docs for this endpoint, since it's based on the generated events and is not using a standard Dto model. I will see if there is any workaround, but you can take a look at the tests written for the endpoint, the data is near the bottom of the file: apps/api-dispute/src/app/tests/test_api.py

apolkingg8 commented 2 years ago

@apolkingg8 It's non-trivial to automatically create API docs for this endpoint, since it's based on the generated events and is not using a standard Dto model. I will see if there is any workaround, but you can take a look at the tests written for the endpoint, the data is near the bottom of the file: apps/api-dispute/src/app/tests/test_api.py

I already checked the py test file. Unfortunately, it's not enough to describe the API design, that's why I create this issue. A document (or a correct spec) is necessary to let somebody co-work on this.

solomondefi-dev commented 2 years ago

What exactly do you need? I can generate curl commands from the py test file if that helps. Can you explain more about why it's not enough to proceed?

apolkingg8 commented 2 years ago

I'm implementing functional tests in https://github.com/SolomonDefi/solomon-monorepo/blob/161_deploy-contract/apps/app-e2e/src/api-dispute.spec.ts . I want to make sure I tested all the cases, so I need the correct spec. If you think the current implementation is enough, that's fine.

solomondefi-dev commented 2 years ago

It's enough to match the events in test_api.py for now. There definitely should be API documentation, but it's not a quick fix, since from what I can tell we can't easily use the python framework's built in doc generation.

Another way we can solve it is by generating contract documentation from the Solidity files. This will contain the events, though it will not include type directly (e.g. "type": "dispute.preorder.created").

solomondefi-dev commented 2 years ago

Latest PR should resolve this, if not please re-open @apolkingg8