全局注释

@APIVersion

@Title

@Description

@Contact

@TermsOfServiceUrl

@License

@LicenseUrl

应用注释

@ApiModelProperty

为 model 类添加注释

SpringBoot 整合 Swagger

Spring Boot中使用Swagger2构建强大的RESTful API文档
 Spring boot集成Swagger2,解决页面不显示的问题
 swagger注释API详细说明
 swagger快速开发
 java swagger ui 添加header请求头参数
 Spring Boot系列十九 Spring boot集成 swagger

Beego 整合 Swagger

1. 创建Beego项目

使用bee new命令创建beego-swagger项目

bee new beege-swagger

在这里插入图片描述

2. 开启自动生成文档

修改conf/app.conf文件,添加如下配置,开启文档自动生成

# 开启自动生成文档
EnableDocs = true

在这里插入图片描述

3. 生成文档

控制台输入如下命令生成文档

# 生成文档,该命令执行后,会在当前项目下生成swagger文件夹及swagger.json,swagger.yml文件
# swaager.json, swagger.yml文件包含各个url的映射信息, 可通过该文件来查看url的映射是否正确
# bee run gendoc=true // 生成文档并运行
bee generate docs

在这里插入图片描述
该命令执行后,会在当前项目下生成swagger目录, 该目录下包含swagger.json, swagger.yml文件

4. 下载Swagger并集成

A. 下载 beego/swagger v2 并将其解压到当前项目的swagger目录下
在这里插入图片描述
B. 修改index.html文件,内容如下

5. Swagger静态目录配置

修改main.go文件, 在main函数中设置beego中swagger静态文件目录

package main

import (
	_ "beego-swagger/routers"
	"github.com/astaxie/beego"
)

func main() {

	// 设置beego中swagger的静态文件目录
	if beego.DEV == "dev" {
		beego.SetStaticPath("/swagger", "swagger")
	}

	beego.Run()
}

6. 路由及命名空间配置

修改router.go文件, 该文件用于配置各个Controller的映射信息, 修改代码如下:

// @APIVersion 1.0.0
// @Title beego Test API
// @Description beego has a very cool tools to autogenerate documents for your API
// @Contact astaxie@gmail.com
// @TermsOfServiceUrl http://beego.me/
// @License Apache 2.0
// @LicenseUrl http://www.apache.org/licenses/LICENSE-2.0.html
// 配置路由映射,以上注解必须添加
package routers

import (
	"beego-swagger/controllers"
	"github.com/astaxie/beego"
)

func init() {
	ns := beego.NewNamespace("/v1",
		// UserController的路由映射
		beego.NSNamespace("/user",
			beego.NSInclude(
				&controllers.UserController{},
			),
		),
		// 其余Controller的路由映射在这里添加...
	)
	beego.AddNamespace(ns)
}

7. Controller及其注解配置

Controller代码的编写, 其中Swagger的配置是通过注解来实现的

package controllers

import (
	"beego-swagger/models"
	"github.com/astaxie/beego"
)

type UserController struct {
	beego.Controller
}

// swagger注解配置
// @Title Get
// @Description get user
// @router /get [Get]
func (userController *UserController) Get() {
	user := &models.User{}
	newUser := user.GetUser()
	userController.Data["json"] = newUser
	userController.ServeJSON()
}

user.go

package models

type User struct {
	Id int
	Name string
}

func (this *User) GetUser() (User) {
	return User{Id:1, Name:"fly"}
}

在配置完Controller之后, 需要重新执行bee generate docs文件, 用以重新生成swagger的映射文件swagger.json, swagger.yml

8. 运行项目

运行项目, 浏览器访问http://localhost:8080/swagger/index.html, 弹出界面如下则表示配置成功
在这里插入图片描述

自动生成文档并运行项目

bee run -gendoc=true -downdoc=true

knife4j

Knife4j
SpringBoot集成Knife4j2.0.2(接口及字段排序、生产环境关闭)

Knife4j文件上传不显示上传选择文本域

原文链接：https://blog.csdn.net/CSDN_FlyYoung/article/details/87931474

分布式_接口文档管理工具

Swagger_学习笔记