0

I generating swagger documentation using fiber swagger package. I have grouped routes that I use exclusively within their domains.

when i make the declarations above the function it works well

// GetDevices godoc
// @Summary Get all Devices
// @ID get-all-devices
// @Description Get all Devices
// @Accept  json
// @Produce  json
// @Tags Devices End Points
// @Success 200 {object} models.Device
// @Failure 400 {object} utils.HTTPError
// @Failure 404 {object} utils.HTTPError
// @Failure 500 {object} utils.HTTPError
// @Router /api/devices/ [get]
func DeviceRoute(route fiber.Router) {
    route.Get("", controllers.GetDevices)
     route.Post("/create", services.CheckMiddleware, controllers.CreateDevice)

}

however, I would want to have every swagger declaration for each route but this does not work when I do as show below

func DeviceRoute(route fiber.Router) {

    // GetDevices godoc
// @Summary Get all Devices
// @ID get-all-devices
// @Description Get all Devices
// @ID get-item-by-int
// @Accept  json
// @Produce  json
// @Tags Devices End Points
// @Success 200 {object} models.Device
// @Failure 400 {object} utils.HTTPError
// @Failure 404 {object} utils.HTTPError
// @Failure 500 {object} utils.HTTPError
// @Router /api/devices/ [get]
    route.Get("", controllers.GetDevices)
    
// Create Device godoc
// @Summary Create a device
// @ID create-device
// @Description  Create a device
// @Accept  json
// @Produce  json
// @Tags Devices
// @param device body models.Device true  "Device details"
// @Success 200 {object} Device
// @Failure 400 {object} utils.HTTPError
// @Failure 404 {object} utils.HTTPError
// @Failure 500 {object} utils.HTTPError
// @Router /api/devices/create [post]
     route.Post("/create", services.CheckMiddleware, controllers.CreateDevice)

}

when I do as above I get No operations defined in spec!

How should I do this for each route that has been expoted and accessed from a function that uses fiber.Router?

Note:when I run swag init, the output of the json file is as follows when the definitions are within the DeviceRoute function

"info": {
        "description": "Teleops IOT server API",
        "title": "Teleops  API",
        "contact": {
            "name": "API Support",
            "email": "info@teleops.io"
        },
        "version": "2.0"
    },
    "host": "localhost:3000",
    "basePath": "/",
    "paths": {}
}
Barty
  • 164
  • 3
  • 10

1 Answers1

2

The doc generator won't look inside functions, only outside them. You're better re-structuring your routing to allow for that, e.g have a Server type that defines methods that your routes call to perform their function.

Daniel Oluojomu
  • 46
  • 1
  • 7
  • Thank you for the pointer. I have wrapped every route into a function like so func DeviceRoute(route fiber.Router) { GetAllDevices(route ) //get add devices CreateDevice(route ) //create a new device GetDevice(route) //get one device DeleteDevice(route) //delete one device UpdateDevice(route) //update one device } then declared swagger details as required and it works. – Barty Oct 09 '21 at 13:25
  • That works too!, but I strongly recommend having a Server struct as mentioned above :) – Daniel Oluojomu Oct 09 '21 at 16:09
  • Thank you I will look at this server struct, I am deep diving into go with a project based approach coming from node.js background. is there a link that you can point me to to get more information on server struct? – Barty Oct 09 '21 at 17:20
  • 1
    Mat Ryer wrote this https://pace.dev/blog/2018/05/09/how-I-write-http-services-after-eight-years.html, i hope it helps! – Daniel Oluojomu Oct 13 '21 at 11:30
  • Thank you for this! – Barty Oct 13 '21 at 18:56