В репозитории библиотеки для работы со swagger на go, подробнее описаны все возможности и правила работы со swgger
https://github.com/swaggo/swag?tab=readme-ov-file
Для запуска примера достаточно запустить exe файл из репозитория Но при таком запуске документация будет не доступна
Для запуска примера с документацией необходимо добавить флаг -d со значением true
swaggerExample.exe -d=true
Для примера добавим endpont, который будет умножать полученные данные
Для этого создадим новый файл папке service и напишем следующий код
package service
import (
"encoding/json"
"net/http"
)
type MultiplicationData struct {
Data []float64
}
type MultiplicationResponce struct {
Sum float64
}
// @Summary Перемножение массива чисел
// @Tags numbers
// @Description Перемножение массива чисел переданого в структуре MultiplicationData
// @ID MultiplicationSlice
// @Accept json
// @Produce json
// @Param data body MultiplicationData true "Данные"
// @Success 200 {object} MultiplicationResponce "success"
// @Failure 400,500 {object} errorResponce "error"
// @Router /Multiplication [post]
func MultiplicationSlice(w http.ResponseWriter, r *http.Request) {
var data MultiplicationData
if err := json.NewDecoder(r.Body).Decode(&data); err != nil {
ErrorResponce(err, "invalid data", http.StatusBadRequest, w)
return
}
var responce MultiplicationResponce
for _, v := range data.Data {
responce.Sum *= v
}
w.Header().Set("Content-Type", "application/json")
if err := json.NewEncoder(w).Encode(responce); err != nil {
ErrorResponce(err, "error encode", http.StatusInternalServerError, w)
}
}На основе комментария над функцией MultiplicationSlice будет составлена документация swagger - ом.
// @Summary - Описание что видно до раскрытия подробной информации
// @Tags - тег для группировок endpoint по какому либо признаку, тег придумывается самостоятельно и является заголовком группы
// @Description - Подробное описание endpoint
// @ID - id endpoint
// @Accept - тип принимаемого запроса
// @Produce - тип отправляемого ответа
// @Param - Принимаемы параметры
`// @Param data body MultiplicationData true "Данные"`
1. data - имя параметра
2. body - где находятся данные, в данном случае в теле запроса, если параметры в запросе то пишется query
3. MultiplicationData - тип данных ответа
4. true - обязательность этого параметра
5. "Данные" - Описание
// @Success - описание успешного ответа
`// @Success 200 {object} MultiplicationResponce "success"`
1. код ответа
2. тип данных ответа
3. тип данных данных внутри кода
4. описание
// @Failure - описание неудачных ответов, заполняется аналогично успешному ответу
// @Router - путь до этого endpoint, без него swagger не документирует
Подробнее о том какие настройки существуют в swagger смотрите в репозитории
Так же добавим в роутер новый endpoint в файле main.go
r.HandleFunc("/Multiplication", service.MultiplicationSlice).Methods("POST")Запустим генерацию обновленной документации
- Убедимся что swagger установлен
go install github.com/swaggo/swag/cmd/swag@latest`- Запустим генерацию
swag init- Соберём новый билд
go buildТеперь можно запустить и увидеть в документации описание нового endpoint