Feature: Convert $PodeContext.server.routes to Swagger/OpenAPI

[LLIT]

Do you have any idea how to convert all the routes to Swagger?

[Badgerati]

I've not had much experience with Swagger/OpenAPI before, so I'll have to investigate properly to see if's possible. From an initial look it appears as though it should just be a case of generating a YAML definition from the routes 🤔

I'll keep digging when I get chance to.

[LLIT]

I am on it as well, and will keep you informed.
It could require some "standards" for how to define the POST body.

In Swagger you can use JSON, that is what i normally do.

[Badgerati]

First commit has basic support for OpenAPI and Swagger. You can enable just OpenAPI, or enable Swagger with it:

Enable-PodeOpenApiRoute -Title 'OpenAPI Example' -Filter '/api/'
Enable-PodeSwaggerRoute

OpenAPI definition by default can be found at /openapi, and Swagger at /swagger.

Going to tackle Responses next.

[Badgerati]

At present, this is a simple example of setting response codes:

Add-PodeRoute -Method Get -Path "/api/resources" -ScriptBlock {
    Set-PodeResponseStatus -Code 200
} -PassThru |
    Set-PodeOpenApiRouteMetaData -Summary 'A cool summary' -Tags 'Resources' -PassThru |
    Add-PodeOpenApiRouteResponse -StatusCode 200 -PassThru |
    Add-PodeOpenApiRouteResponse -StatusCode 404

and this is a more complicated example for request path parameters, and response schema:

Add-PodeRoute -Method Get -Path '/api/users/:userId' -ScriptBlock {
    param($e)
    Write-PodeJsonResponse -Value @{ Name = 'Rick'; UserId = $e.Parameters['userId'] }
} -PassThru |
    Set-PodeOpenApiRouteMetaData -Summary 'A cool summary' -Tags 'Users' -PassThru |
    Set-PodeOpenApiRouteRequest -Parameters @(
        New-PodeOpenApiRouteRequestParameter -Integer -Name 'userId' -In Path -Required
    ) -PassThru |
    Add-PodeOpenApiRouteResponse -StatusCode 200 -Description 'A list of users' -Schemas @(
        New-PodeOpenApiSchema -Object -ContentType 'application/json' -Properties @(
            New-PodeOpenApiSchemaProperty -Name 'Name' -String
            New-PodeOpenApiSchemaProperty -Name 'UserId' -Integer
        )
    )

[Badgerati]

Things left to look at:

• Authentication
• Possibly have a -RestrictRoutes switch on enabling OpenApi, so it only shows routes available for the current URI being used
• Maybe a dark mode on the inbuilt swagger? 👀 @Fraham

[Fraham]

👀

[ArieHein]

Would these help in anyway ?

https://github.com/beatcracker/POSH-swagger-codegen
and the AutoRest one:

https://github.com/Azure/autorest

perhaps checking the results or getting ideas from

[Badgerati]

AutoRest I'm aware of, was going to use it during testing 😃

They're obviously a little different, as they're consuming an OpenAPI definition; building one is a whole other nightmare, haha 😂

I currently have pretty much all of the basics working. I'm just working on a refactor to make RequestBody/Response schemas simpler - then onto testing!

[Badgerati]

Last commit is a big refactor on simplifying setting RequestBody and Response schemas.

Next is to tackle Component Schemas, so we can reference generic schemas.

[Badgerati]

Added in ReDoc support on top of the Swagger support

[majkinetor]

Nice. Redoc rocks.