[Feature Request]: add Swagger - automated API documentation

[bugITwhisperer]

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:

• https://docs.potterdb.com/apis/rest
• https://docs.potterdb.com/apis/graphql

(Optional) Describe a solution for this feature

No response

(Optional) Screenshots

No response

[danielschuster-muc]

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]

@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]

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

[manoellvitor]

@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]

@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?