در گولنگ می‌توان به دو صورت تک خطی یا چند خطی, درون کد, کامنت (comment) گذاشت.

package main

// one line comment
func main() {
    /*
        multiline
        comment
    */
}

کامنت ها معمولا توضیحاتی در مورد کد هستند که برای برنامه نویس ها نوشته می‌شوند. در گولنگ یکسری دستورات خاص برای نوشتن کامنت وجود دارند که قابلیت هایی را درون خط فرمان Go فعال می‌کنند. یکی از این دستورات ‍go:generate است که با استفاده از آن میتوان یک دستور خط فرمان را درون کد به صورت کامنت نوشت و سپس با استفاده از دستور go generate اجرا کرد.

package main

import "log"

//go:generate echo "This is a message from go generate"
func main() {
    log.Println("Hello world!")
}

در کد بالا کامنت خود را با go:generate شروع کردیم و سپس یک دستور echo را قرار دادیم. در صورتی که دستور go generate را درون پوشه ای که فایل بالا قرار دارد اجرا کنیم متن This is a message from generate درون صفحه چاپ می‌شود.

به‌صورت کلی go:generate این امکان را فراهم می‌کند که مجموعه‌ای از دستورات موردنیاز برای خودکارسازی کارها مانند تولید کد، ساخت فایل‌های کمکی، اجرای ابزارهای جانبی را مستقیماً درون سورس‌کد تعریف کنیم. این دستورات به شکل کامنت‌های ویژه در کد قرار می‌گیرند و سپس با اجرای دستورgo generate در خط فرمان، همگی به‌صورت یکپارچه اجرا می‌شوند. 

به این ترتیب، فرآیندهایی که وابسته به کد هستند در کنار همان کد مستندسازی و نگهداری می‌شوند و وابستگی آن‌ها شفاف‌تر می‌شود. در واقع، کاری که go generate انجام می‌دهد ذاتاً متفاوت از ابزارهایی مانند Make یا Taskfile نیست و می‌توان همان عملیات را با آن‌ها نیز پیاده‌سازی کرد. اما مزیت مهم go generate این است که بخشی از ابزار رسمی زبان Go محسوب می‌شود؛ بنابراین در هر محیطی که Go نصب باشد، دستور go نیز در دسترس است و نیازی به نصب، تنظیمات یا وابستگی اضافی به ابزارهای جانبی نخواهیم داشت. این موضوع باعث می‌شود فرآیند تولید کد ساده‌تر، قابل‌حمل‌تر و هماهنگ‌تر با اکوسیستم Go باشد.

قابلیت go generate اولین بار در فوریه 2015 و همراه با انتشار Go 1.4 معرفی شد. از آن زمان تاکنون، این دستور به‌عنوان بخشی رسمی از ابزار خط فرمان go در تمام نسخه‌های بعدی وجود دارد و نیاز به نصب جداگانه‌ای ندارد.

در ادامه با استفاده از go:generate فایل های openapi رو برای کد گولنگی خودمون تولید میکنیم.

تولید فایل‌های openapi/swagger برای کد گولنگ

در اینجا به صورت خلاصه توضیح میدیم چطور go:generate به ما کمک میکنه تا مستندات openapi رو تولید کنیم و کدمون رو باهاش ادغام کنیم.

برای ادغام با openapi ابتدا ابزار swag را به صورت زیر نصب می‌کنیم:

go get -u -tool github.com/swaggo/swag/cmd/swag@latest

سپس کد را با استفاده از annotation های swagger  نشانه گذاری می‌کنیم:

package api

import "net/http"

// @title Simple Go API
// @version 1.0
// @description This is a simple API built with Go and documented with Swagger.
// @host localhost:8090
// @BasePath /
func StartServer() error {
    mux := http.NewServeMux()

    mux.HandleFunc("/hello", HelloWorld)

    return http.ListenAndServe(":8090", mux)
}

// @Summary Hello World Endpoint
// @Description Responds with "Hello World"
// @Tags example
// @Produce text/html
// @Success 200 {string} string "Hello World"
// @Router /hello [get]
func HelloWorld(w http.ResponseWriter, r *http.Request) {
    w.WriteHeader(http.StatusOK)
    w.Write([]byte("Hello World"))
}

سپس در فایل main.go  دستور مربوط به ایجاد مستندات را به صورت زیر بنویسیم:

package main

import (
    "log"
    "swagger/api"
)

//go:generate go tool swag init --generalInfo api/api.go --output ./docs
func main() {
    if err := api.StartServer(); err != nil {
        log.Fatalln(err)
    }
}

حالا با استفاده از دستور go generate می‌توانیم مستندات را تولید کنیم. مستدات درون پوشه docs در کنار فایل main.go قرار می‌گیرند.حالا به یک صفحه وب نیاز داریم تا بتونیم فایل هایی که generate شده اند رو نمایش بدیم. برای اینکار از پکیج زیر استفاده میکنیم:

go get -u github.com/swaggo/http-swagger/v2

بعد از نصب پکیج بالا باید یه اندپوینت مشخص کنیم که UI روی اون مسیر لود بشه برامون و همچنین داکیومنت هایی که در مرحله قبل generate کردیم رو ایمپورت میکنیم تا توسط UI مورد استفاده قرار بگیرند.

package api

import (
    "net/http"

    _ "swagger/docs"

    httpSwagger "github.com/swaggo/http-swagger/v2"
)

// @title Simple Go API
// @version 1.0
// @description This is a simple API built with Go and documented with Swagger.
// @host localhost:8090
// @BasePath /
func StartServer() error {
    mux := http.NewServeMux()

    mux.HandleFunc("/hello", HelloWorld)
    mux.HandleFunc("/openapi/", httpSwagger.Handler())

    return http.ListenAndServe("0.0.0.0:8090", mux)
}

// @Summary Hello World Endpoint
// @Description Responds with "Hello World"
// @Tags example
// @Produce text/html
// @Success 200 {string} string "Hello World"
// @Router /hello [get]
func HelloWorld(w http.ResponseWriter, r *http.Request) {
    w.WriteHeader(http.StatusOK)
    w.Write([]byte("Hello World"))
}

در نهایت با دستور go run main.go برنامه را اجرا میکنیم. حالا با باز کردن ادرس localhost:8090/openapi درون یک مرورگر وب, باید بتونیم چیزی شبیه تصویر زیر رو ببینیم.

کدهای کامل مربوط به این بخش رو میتونید در Github مشاهده کنید.

ما این مقاله را از روی مقاله اصلی منتشر شده در سایت گولنگ ترجمه و یکسری موارد تکمیلی رو به اون اضافه کردیم.

قسمت قبل: reflection | گولنگ به زبان ساده

قسمت بعد:‌ به زودی…