小工具      在线工具  汉语词典  css  js  c++  java

swaggo使用教程

Go,swagger,swaggo,go 额外说明

收录于:158天前

安装与初始化

  1. 安装插件

go install github.com/swaggo/swag/cmd/swag@latest

  1. 安装依赖项

go get -u github.com/swaggo/swag/cmd/swag

  1. 在包含main.go文件的项目根目录运行swag init。这将会解析注释并生成需要的文件(docs文件夹和docs/docs.go)。

swag init

一定要在main.go的统计目录下,不然会出现如下错误:

在这里插入图片描述
切换到main.go统计目录后重新生成:

在这里插入图片描述
生成了一个docs目录

在这里插入图片描述
在这里插入图片描述
上述文件是根据swagger的注解生成的,虽然现在还没有swagger的注解,但是会生成默认的文件。

在项目开发过程中,很明显所有的API不可能都写在一个go源文件中,需要统一生成。

swag init -g http/api.go

  1. 还可以使用fmt来格式化swagger注释

swag fmt

基本命令

swag init -h
NAME:
   swag init - Create docs.go

USAGE:
   swag init [command options] [arguments...]

OPTIONS:
   --generalInfo value, -g value          API通用信息所在的go源文件路径,如果是相对路径则基于API解析目录 (默认: "main.go")
   --dir value, -d value                  API解析目录 (默认: "./")
   --exclude value                        解析扫描时排除的目录,多个目录可用逗号分隔(默认:空)
   --propertyStrategy value, -p value     结构体字段命名规则,三种:snakecase,camelcase,pascalcase (默认: "camelcase")
   --output value, -o value               文件(swagger.json, swagger.yaml and doc.go)输出目录 (默认: "./docs")
   --parseVendor                          是否解析vendor目录里的go源文件,默认不
   --parseDependency                      是否解析依赖目录中的go源文件,默认不
   --markdownFiles value, --md value      指定API的描述信息所使用的markdown文件所在的目录
   --generatedTime                        是否输出时间到输出文件docs.go的顶部,默认是
   --codeExampleFiles value, --cef value  解析包含用于 x-codeSamples 扩展的代码示例文件的文件夹,默认禁用
   --parseInternal                        解析 internal 包中的go文件,默认禁用
   --parseDepth value                     依赖解析深度 (默认: 100)
   --instanceName value                   设置文档实例名 (默认: "swagger")

swag fmt -h
NAME:
   swag fmt - format swag comments

USAGE:
   swag fmt [command options] [arguments...]

OPTIONS:
   --dir value, -d value          API解析目录 (默认: "./")
   --exclude value                解析扫描时排除的目录,多个目录可用逗号分隔(默认:空)
   --generalInfo value, -g value  API通用信息所在的go源文件路径,如果是相对路径则基于API解析目录 (默认: "main.go")
   --help, -h                     show help (default: false)

swagger主键嵌入接口

Swagger一般通过源码嵌入到接口中,用于生成接口的在线测试页面和API文档。

swago常用的注解,注解的形式嵌入到go源码中,如下

// @Summary 接口简介:获取hello方法
// @Description 接口描述:这是一个没有入参,出参为hello信息的接口
// @Tags 测试
// @Accept json
// @Produce json
// @Param user_id path string true "用户ID" minlength(1) maxlength(100)
// @Success 200 {object} Response
// @Failure 400 {object} Response
// @Failure 404 {string} string "{"msg":"找不到路径了0.0"}"
// @Failure 500 {object} Response
// @Router /hello [get] --> 路由地址和请求方法
  • @Summary,接口介绍
  • @Description,接口描述
  • @Tags,接口标签,用于对API进行分组
  • @Accept,接口接收的输入参数类型,支持mpfd(form)、json等。
  • @Produce,接口返回的参数类型,支持mpfd(form)、json等。
  • @Param,输入参数定义
  • @Success,指定成功响应的数据,格式为1.HTTP响应码2.响应参数类型3.响应数据类型4.其他说明
  • @Failure,失败响应后的数据与Success相同
  • @Router,指定路由和HTTP方法

原生net/http库使用swag

github地址https://github.com/swaggo/http-swagger

单纯下载sawg只能生成API文档,无法生成在线文档并在线测试。因此,您还需要下载特定的依赖项来集成Web界面服务。

对于原生的net/httpswago官方提供了github.com/swaggo/http-swagger用于生成在线api文档。

  1. http=swagger 下载依赖项

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

  1. 引入依赖

import "github.com/swaggo/http-swagger"

  1. 下载依赖,根据http接口注解生成在线api

go get github.com/swaggo/http-swagger/example/go-chi/docs

  1. 下载在线api测试服务器的依赖

go get github.com/go-chi/chi

使用整合swagger的httpSwagger编写api接口,并使用swagger注释,代码如下:

package main

import (
	"net/http"

	"github.com/go-chi/chi"
	httpSwagger "github.com/swaggo/http-swagger"
	_ "github.com/swaggo/http-swagger/example/go-chi/docs" // docs is generated by Swag CLI, you have to import it.
)

// @title Swagger Example API
// @version 1.0
// @description This is a sample server Petstore server.
// @termsOfService http://swagger.io/terms/

// @contact.name API Support
// @contact.url http://www.swagger.io/support
// @contact.email [email protected]

// @license.name Apache 2.0
// @license.url http://www.apache.org/licenses/LICENSE-2.0.html

// @host petstore.swagger.io
// @BasePath /v2
func main() {
    
	r := chi.NewRouter()
	r.Get("/swagger/*", httpSwagger.Handler(
		httpSwagger.URL("http://localhost:1323/swagger/doc.json"), //The url pointing to API definition
	))

	http.ListenAndServe(":1323", r)
}

  1. 访问swagger在线api,任何sawgger结合的api接口在线了地址都是http://ip:端口/swagger/index.html

在这里插入图片描述

swaggo支持若干很多web框架,具体请移步赃物

. . .

相关推荐

额外说明

C#WPF项目开发(一)(火车票订票系统)

C#WPF 项目开发(一)(火车订票系统) 一、架构模式 I.了解架构模式 1.如何设计大型企业级的系统,在开始主要的代码开发之前,我们必须选择一种 合适的体系架构。 (1)、架构模式是对给定上下文的软件架构中常见问题的一种通用的可复用的解决方案。一种模

额外说明

认证/支付/优惠劵策略模式-security多源认证

文章目录 一.为什么要采用策略模式 二.业务流程 2.1 AuthenticationManagerProcessingFilter认证过滤器 SpringContextUtil上下文引用工具类 2.2 AuthEnums枚举 2.3策略模式上下文 2.

额外说明

ge ren chen zhang

8.28 今天第一次写博客,也是因为看了网上的几篇文章吧 先说一下自己感觉的写博客的好处吧。 1: 有助于对当天学到知识的吸收。 2:好记性不如烂笔头,记下来方便以后的查找。 3:有以一种成就感。 4 :可以结交一些志同道合的朋友吧。 5:可以监督一下自

额外说明

xshell7,xftp7个人免费版官方下载,无需破解,免激活,下载即可使用

对于开发人员来说,xshell这款软件应该不陌生,是一款非常好用的服务器连接工具,但同时它又是收费的,导致很多同学下载后使用不久后就到期了。于是很多人都去网上搜索绿色版、破解版的,结果搜索出来的要么是有很多的捆绑软件,要么就是病毒软件。Xshell 很多

额外说明

Java二叉树进阶面试题讲解

Java二叉树进阶面试题讲解 -1.二叉树的构建及遍历- -2.二叉树的分层遍历- -3.给定一个二叉树, 找到该树中两个指定节点的最近公共祖先- -4.二叉树搜索树转换成排序双向链表- -5.根据一棵树的前序遍历与中序遍历构造二叉树- -6.根据一棵树

额外说明

MySQL搭建

1、以windows为例,进入官方下载页面https://dev.mysql.com/downloads/mysql/ 2、将下载好的文件进行解压,如下: 3、在目录中新建data文件夹和my.ini文件 4、在my.ini中输入如下配置项 [mysql

额外说明

vue-rx的初步使用

一、各文档介绍 1、rxjs官网 2、vue-rxjs地址 二、环境搭建 1、使用vue-cli构建一个项目 2、安装vue-rx的依赖包 yarn add rxjs yarn add rxjs-compat yarn add vue-rx 3、在sr

额外说明

解决IDEA支持GBK编码项目的问题

关键字: 如何阻止IDEA自动切换项目为UTF8编码, 项目GBK编码, IDEA切换GBK编码   问题描述 在开发一些老系统时,还是采用传统的GBK编码, 当在IDEA里设置项目编码为GBK时, 经过一次代码更新,或者分支切换,或者刷新一下maven

额外说明

9个适用于WordPress的最佳音频播放器插件

WordPress 内置支持处理各种格式的音频文件。它可以自动嵌入支持格式的音频文件,但如果您需要更多功能(例如播放列表、自定义选项等)怎么办?在本文中,我们精心挑选了适用于 WordPress 的 bet 音频播放器插件。 WordPress 内置支持

ads via 小工具