(原文作者:Arnesh Agrawal)

为什么是Beego？

Beego是一个RESTful HTTP框架，用于在Golang中开发Web应用程序和API，并遵循Model-View-Controller（MVC）体系结构。它支持用Swagger来自动生成文档，这使我们的工作更加轻松。

在本文中，我将讨论Beego框架的基础知识以及Swagger如何在文档中为我们提供帮助。

先决条件

• 进入设置（遵循此https://www.digitalocean.com/community/tutorials/how-to-install-go-on-ubuntu-18-04）
• Beego安装（遵循此https://beego.me/quickstart）

让我们开始吧

假设您已经成功设置了Go and Beego，就该开始了！
首先，我希望您在终端中运行一个简单的命令。

bee

这应该输出类似：

如果您的输出与此匹配，则表明您已成功设置了此项目所需的所有内容。如果不是，请继续解决该问题。

让我们为本教程创建一个新的API，将其命名为test_api

bee api test_api

该命令将创建一个目录“ test_api”，其中包含以下文件夹和文件：

-conf
-controllers
-main.go
-models
-routers
-tests

简而言之，路由器是指定端点的地方(https://stackoverflow.com/questions/30580562/what-is-the-difference-between-resource-and-endpoint)，控制器是API的大脑，模型是用于控制器所需的数据处理的地方，而conf是用于存储凭据和有关API的其他信息的配置文件。

默认情况下，我们已经在routers目录的router.go文件中创建了“用户”和“对象”端点。

func init() {
	ns := beego.NewNamespace("/v1",
		beego.NSNamespace("/object",
			beego.NSInclude(
				&controllers.ObjectController{},
			),
		),
		beego.NSNamespace("/user",
			beego.NSInclude(
				&controllers.UserController{},
			),
		),
                beego.NSNamespace("/test",
			beego.NSInclude(
				&controllers.TestController{},
			),
		),
	)
	beego.AddNamespace(ns)
}

(https://gist.github.com/Arnesh07/e5441e7a2d1b223aa9179f7946c38ae6/raw/badc66e7c4efd47dc1b4fd6f8df5ea136c51b049/router.go)

此代码段指定端点v1/object由处理ObjectController。我已经test按照本教程的类似规范创建了一个端点。现在，我们可以在这里忽略所有其他关键字，而只关注端点和处理端点的控制器。
每当对v1/test端点执行调用时，都会执行内部的逻辑TestController。

现在，我们需要制作两个新文件：控制器中的test.go和模型中的test.go。
控制器中的test.go基本上是TestController，模型的文件是此特定控制器的模型。

package controllers

import (
	"test_api/models"
	"github.com/astaxie/beego"

)

type TestController struct {
	beego.Controller
}

// @Title TestEndpoint
// @Description Tests the API
// @Success 200 {object} models.Test
// @Failure 403 body is empty
// @router /hello [get]
func (t *TestController) Test() {
	Response := models.TestFunction()
	t.Data["json"] = Response
	t.ServeJSON()  
}

(https://gist.github.com/Arnesh07/e5441e7a2d1b223aa9179f7946c38ae6/raw/badc66e7c4efd47dc1b4fd6f8df5ea136c51b049/router.go)

每个控制器的布局都是相同的，因此我们实际上可以在此处使用用户控制器的代码，并根据需要对其进行修改。关于函数Test()，只要执行此函数，Response变量就会TestFunction在模型中调用该函数并存储接收到的数据。然后，控制器将数据编码为JSON形式并返回。

这很简单
但是在这里更重要的是要理解之前的评论TestFunction。
这些注释实际上在API和文档中起作用。
这些评论@Title和@Description是自描述它们的功能和使用是对文件的。
@Success并分别@Failure指示对端点执行成功和失败的响应。这些注释后的整数表示响应代码，这些整数后的值表示返回类型。这些注释也用于文档。
最后一条评论@Router暗示了端点将是什么及其功能。/hello后@Router是在router.go中指定的初始端点之外的功能，即在Test需要端点时执行该功能v1/test/hello。[get]表示HTTP请求是GET请求。在此处
了解有关HTTP请求的更多信息。可以得到有关在Beego框架这样的评论的详细解释在这里。

进入模型的代码：

package models

import (
	
)

type Test struct {
	Response string 
}

func TestFunction() Test {
	 var test_var Test 
	 test_var.Response = "Hello World"
	 return test_var
}

(https://gist.github.com/Arnesh07/920b42ad5cb18f24355598e801d9344f/raw/6893700f4b04f57c53df196c21fd4539d555bfa8/test.go)

功能TestFunction，具有返回类型结构Test，是由控制器调用。它为该结构创建一个新变量，分配Response为“ Hello World”并返回该结构。
所有数据处理和修改都应在此处执行。

恭喜你！我们已经完成了本教程的API编码。现在是时候测试我们的API并生成一些文档了。

bee run

在目录中使用此命令test_api来运行我们的本地服务器以测试我们的端点。现在，打开浏览器并输入：

http://localhost:8080/v1/test/hello

输出应为：

{
  "Response": "Hello World"
}

现在开始自动生成文档，结束服务器的会话并使用以下命令：

bee run -gendoc=true -downdoc=true

现在，转到浏览器并输入：

http://localhost:8080/swagger/

这是我们API的自动生成的文档。我们可以查看端点的文档。

瞧！本教程到此结束。我希望您从中学到了一些有价值的东西。我在下面发布了一些重要链接，以帮助您更好地开发Beego。

链接

• https://tour.golang.org/welcome/1（要学习Golang的基础知识）
• https://beego.me/docs/intro/（Beego文档）
• https://golang.org/doc/（Golang文档）
• https://solidgeargroup.com/best-practices-rest-api/（开发API的良好做法）

PS-除非另有说明，否则我要求拥有本博客文章中使用的所有图片和代码段的所有权利。

谢谢你！

原文地址:

https://medium.com/mobile-development-group/how-beego-swagger-can-make-coding-an-api-easier-227b56055cbc