[Feature Request]: add Swagger - automated API documentation

danielschuster-muc / potter-db

A Harry Potter database for all your wizarding needs: Books, Characters, Movies, Spells, and Potions. Powered by https://github.com/danielschuster-muc/scrabby

https://potterdb.com

MIT License

96 stars 38 forks source link

[Feature Request]: add Swagger - automated API documentation #810

Open bugITwhisperer opened 9 months ago

bugITwhisperer commented 9 months ago

Project

API (api.potterdb.com)

Describe the feature you want to request

Self-explanatory Swagger that would not necessarily replace but extend existing GraphQL and REST API documentation:

(Optional) Describe a solution for this feature

No response

(Optional) Screenshots

No response

danielschuster-muc commented 9 months ago

We already have our Swagger / OpenApi Specification, have a look at the endpoint or with rswag autogenerated file. However it is doesn't have graphql implemented yet. Regarding displaying the interactive swagger ui, I would prefer to add it into the docs.

I am looking forward to hearing any ideas and feedback regarding the whole OAS/Swagger topic.

bugITwhisperer commented 9 months ago

@danielschuster-muc : Yeah, my idea was to have the interactive swagger ui displayed in the documentation - sorry for not being crystal clear here :)

danielschuster-muc commented 9 months ago

@bugITwhisperer sounds good! Feel free to create a pr for adding the swagger ui to the docs.

manoellvitor commented 6 months ago

@danielschuster-muc , There are some OAS disconformity:

Error: Instance failed to match all required schemas (matched only 0 out of 2) --- Object instance has properties which are not allowed by the schema: ["data";"links";"meta"]


{
    "meta": {
        "pagination": {
            "current": 80,
            "first": 1,
            "prev": 79,
            "records": 7
        },
        "copyright": "Copyright © Potter DB 2024",
        "generated_at": "2024-03-06T15:46:56.357+00:00"
    },
    "links": {
        "self": "https://api.potterdb.com/v1/books?page%5Bnumber%5D=80&sort=worryingly",
        "current": "https://api.potterdb.com/v1/books?page[number]=80&sort=worryingly",
        "first": "https://api.potterdb.com/v1/books?page[number]=1&sort=worryingly",
        "prev": "https://api.potterdb.com/v1/books?page[number]=79&sort=worryingly"
    },
    "data": [

    ]
}

danielschuster-muc commented 5 months ago

@danielschuster-muc , There are some OAS disconformity:

Error: Instance failed to match all required schemas (matched only 0 out of 2) --- Object instance has properties which are not allowed by the schema: ["data";"links";"meta"]

{
    "meta": {
        "pagination": {
            "current": 80,
            "first": 1,
            "prev": 79,
            "records": 7
        },
        "copyright": "Copyright © Potter DB 2024",
        "generated_at": "2024-03-06T15:46:56.357+00:00"
    },
    "links": {
        "self": "https://api.potterdb.com/v1/books?page%5Bnumber%5D=80&sort=worryingly",
        "current": "https://api.potterdb.com/v1/books?page[number]=80&sort=worryingly",
        "first": "https://api.potterdb.com/v1/books?page[number]=1&sort=worryingly",
        "prev": "https://api.potterdb.com/v1/books?page[number]=79&sort=worryingly"
    },
    "data": [

    ]
}

Could you please open a seperate issue for this problem with more details?