Closed harrislineage closed 7 months ago
MichalVasut
commented
7 months ago btw, the YAML config seems to be invalid - check here: https://editor-next.swagger.io/
but that is maybe due to "non-standardly" designed API
action) - standardly differentiated by endpoint
Clarke-11007
commented
7 months ago Sorry for asking what is probably a basic question that may have been answered earlier, but, how can I view the swagger documentation of the WikiTree API ? I can get a view of the index.html file (on GitHub), but can't find a link that actually shows me a webpage with documentation to the API ...
Thanks!
On Fri, Apr 12, 2024 at 5:40 AM Michal Vašut @.***> wrote:
btw, the YAML config seems to be invalid - check here: https://editor-next.swagger.io/
— Reply to this email directly, view it on GitHub https://github.com/wikitree/wikitree-api/pull/9#issuecomment-2051414265, or unsubscribe https://github.com/notifications/unsubscribe-auth/A3JDGBXHPEULV4JRNVFTMWTY46TYVAVCNFSM6AAAAABFOV4JWWVHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZDANJRGQYTIMRWGU . You are receiving this because you are subscribed to this thread.Message ID: @.***>
harrislineage
commented
7 months ago @MichalVasut @Clarke-11007
Hey guys, I've been working on this one. It is meant to be an early version and visual representation / playground for the WikiTree API. As Michal pointed out, the YAML doesn't conform to the typical OpenAPI structure. This is because our API has a unique design with a single endpoint offering multiple actions.
While it may not follow the standard Swagger expectation, it accurately represents the WikiTree API's functionality and generates valid request URLs. I went ahead and proceeded in this direction so that each action would have it's own path, and make it a little easier for newer developers who want to discover how to request data from the API. In the future, we could also publish a version that follows the OpenAPI standards more closely.
If you would like, you can play with it here: https://apps.wikitree.com/apps/harris5439/swagger/
Edit: I have not yet implemented authentication, so make sure you are logged in to the API server if you are going to try private / restricted data.
Edit 2: Brian has this published now on the apps server: https://apps.wikitree.com/apps/wikitree-api/swagger/
@bcaseyrls cool - it's way better for docs browsing - is the endpoint with the docs ready? (well, I can copy&paste the yaml to online viewer)
do you intend to also use that yaml for some validation or even API generation?
At my previous job, we've used it to build the API itself (well, in python - https://connexion.readthedocs.io/en/latest/ ), but I'm not sure how capable PHP is, in this matter.
Btw, as for Connexion, it's really awesome - you only provide business logic, as a simple demo
https://connexion.readthedocs.io/en/latest/quickstart.html#registering-an-api