`openapi.yaml` support?

[BenWolfaardt]

Hi team.

thanks for your awesome products! I was wondering if there is the possibility of serving an openapi.yaml file as opposed to the standard swagger.json? If yes, fantastic news, can you guide me towards some documentation, please. If not, is it planned for a future version?

Thanks and kind regards,

[ubogdan]

@BenWolfaardt Thanks for your appreciation. Unfortunately, we are embedding the JSON file into the generated documentation.

You should be able to serve the generated yaml file using the gin-swagger handler by taking advantage of URL method and adding an additional static handler for your "swagger.yaml".

Something like this. (untested)

package main

import (
    "github.com/gin-gonic/gin"
    "github.com/swaggo/files"
    "github.com/swaggo/gin-swagger"

    "github.com/swaggo/gin-swagger/example/basic/api"

    _ "github.com/org_name/project_name/docs"
)

func main() {
    r := gin.New()

        r.StaticFile("/swagger/swagger.yml", "./swagger/swagger.yml")
    r.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerFiles.Handler,  ginSwagger.URL("static/swagger.yml")))

    r.Run()
}

[BenWolfaardt]

Good morning @ubogdan,

thanks for your swift reply :)

I'm very new to the world of development and especially Go, so still trying to figure out how a lot of things work - there's a lot of trial and error...

I was able to get your above code to "work" by modifying it as follows:

package main

import (
    "github.com/gin-gonic/gin"
    swaggerFiles "github.com/swaggo/files"
    ginSwagger "github.com/swaggo/gin-swagger"
)

func main() {
    r := gin.New()

    r.StaticFile("/docs/swagger.yaml", "./docs/swagger.yaml")
    r.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerFiles.Handler, ginSwagger.URL("docs/swagger.yaml")))

    r.Run(":8888")
}

Please note that the routing and relative paths are still a bit tricky for me, so please see the below file structure to ensure that I have correctly specified paths where they need to be specified:

/home/ben/swaggo_gin-swagger/
├── docs
│   └── swagger.yaml
├── go.mod
├── go.sum
├── go-swagger_test (executable)
└── main.go

The above is the only way I get my terminal not to throw a: [GIN-debug] GET /swagger/*any --> github.com/swaggo/gin-swagger.CustomWrapHandler.func1 (1 handlers) panic: catch-all conflicts with existing handle for the path segment root in path '/swagger/*any' issue.

My terminal's output is as follows:

$ ./go-swagger_test 
[GIN-debug] [WARNING] Running in "debug" mode. Switch to "release" mode in production.
 - using env:   export GIN_MODE=release
 - using code:  gin.SetMode(gin.ReleaseMode)

[GIN-debug] GET    /docs/swagger.yaml        --> github.com/gin-gonic/gin.(*RouterGroup).StaticFile.func1 (1 handlers)
[GIN-debug] HEAD   /docs/swagger.yaml        --> github.com/gin-gonic/gin.(*RouterGroup).StaticFile.func1 (1 handlers)
[GIN-debug] GET    /swagger/*any             --> github.com/swaggo/gin-swagger.CustomWrapHandler.func1 (1 handlers)
[GIN-debug] Listening and serving HTTP on :8888

When I go to http://localhost:8888/swagger/index.html I get:
"Failed to load API definition. Fetch error: Not Found docs/swagger.yaml"
I've tried various paths inside the explore "search bar" at the top of the index.html site with no success.

Any pointers as to what I'm doing incorrectly please?

[ubogdan]

Hi, If you try to open the following URL in your browser http://localhost:8888/docs/swagger.yaml , does it returns the yaml file ? if yes, you should change the URL to inSwagger.URL("/docs/swagger.yaml")

[BenWolfaardt]

Hey, you're absolutely AMAZING, that solved the problem :) thank you so very much!

On a side note, do you have any recommendations of resources that I can study to improve my understanding in the domain of API's / servers particularly in the Go context, places where I can practice/improve my gin knowledge for example?

Thanks, have an awesome day :)