Go-Swagger: можно ли создать спецификацию Swagger для нескольких рабочих пространств одновременно?
Я следую инструкциям https://swagger.io/specification/, чтобы сгенерировать спецификацию Swagger из моего кода. Мой проект состоит из нескольких сервисов, и у меня есть корневая папка, в которой есть несколько рабочих областей (у меня есть рабочая область для каждой службы). Внутри корневой папки находится только файл go.work, в котором указан путь к каждому рабочему пространству. Структура моего проекта следующая:
myworkspaceRoot/
├── go.work
├── go.work.sum
├── Subfolder
├──── workspace1/
│ ├── go.mod
│ └── ...
├──── workspace2/
│ ├── go.mod
│ └── ...
└──── workspace3/
├── go.mod
└── ...
Каждое рабочее пространство — это уникальный сервис со своим основным файлом и зависимостями. Мне удалось создать файлы спецификаций Swagger для каждого рабочего пространства индивидуально, но я хочу создать новый файл спецификаций, содержащий документацию для всей системы. Возможно ли это сделать с моими текущими настройками? Поскольку Go-Swagger запускается из файла и сканирует каждый путь (если я не ошибаюсь), моей первой идеей было создать основной файл в корневой папке и импортировать все пакеты, но это, конечно, было бесполезно, поскольку мне дали ошибка, что в пакете был переобъявлен main (что, я думаю, можно решить, разделив каждый каталог, но это не подходит моему проекту).
Следовательно, если я просто запущу команду swagger generate spec -o swagger.yml --scan-models в корневой папке без каких-либо дополнительных действий, она сгенерирует пустой файл swagger.yml, как и ожидалось.
Второй вариант — всегда писать сценарий, который объединяет все сгенерированные спецификации для отдельных сервисов, но я искал более интуитивный ответ, если он существует.
Ответы 1
Итак, моя первоначальная идея была верной, но реализация не очень, и это стало причиной моей неудачи. По сути, план состоит в том, чтобы создать файл Go в корневой папке, который действует как мета-сервис; Импортируем путь ко всем пакетам, которые мы хотим задокументировать, чтобы Swagger имел к ним доступ, и начинаем генерировать спецификации из этого файла. Причина неудачи в первый раз заключалась в том, что все пакеты, которые я хотел импортировать, были основными пакетами, что делало их исполняемыми файлами, а не импортируемыми библиотеками.
В Go main — это специальное имя пакета, которое указывает, что пакет содержит код исполняемого приложения. То есть это указывает на то, что пакет содержит код, который можно встроить в двоичный файл и запустить.
Для получения дополнительной информации прочитайте этот блог. Итак, я изменил имя пакетов рабочих пространств с основного, что, в свою очередь, изменило тип пакетов. Обратите внимание: я не работал над реальным проектом и, следовательно, не беспокоился о последствиях внезапного изменения имени и типа пакета. В реальном проекте при этом следует проявлять большую осторожность, и если изменение типа пакета невозможно, найдите лучшее решение (например, одна идея может заключаться в переносе необходимых методов в другой пакет Go типа библиотеки или написании скрипт для объединения спецификаций Swagger). В общем, вот так выглядит мой meta.go:
package main
import (
"fmt"
_ "example.com/workspace1"
_ "example.com/workspace2"
_ etc.
)
func doc() {
fmt.Println("Meta service online")
}
И если бы я хотел добавить к этому файлу файл go.mod, это выглядело бы примерно так:
module example.com/Meta
go 1.22.2
replace example.com/Workspace1 => ./Subfolder/workspace1
require example.com/Workspace1 v0.0.0