Swagger Editor 教程

最新推荐文章于 2025-03-20 13:45:32 发布

qq_1443036119

最新推荐文章于 2025-03-20 13:45:32 发布

阅读量3.8k

点赞数 2

文章标签： swagger2 api go node.js golang

本文链接：https://blog.csdn.net/qq_43256905/article/details/111579707

版权

Swagger Editor 教程

文章目录

Swagger Editor 教程

一、swagger 是什么

在这里插入图片描述

OpenAPI 是描述 REST API 的标准规范。 OpenAPI 描述允许人类和计算机无需首先阅读文档或了解实现实现即可发现 API 的功能。
而 Swagger 则是 OpenAPI 的工具集，它是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。
Swagger 是一个简单但功能强大的 API 表达工具。使用 Swagger 生成 API，我们可以得到交互式文档，自动生成代码的 SDK 以及 API 的发现特性等
go-swagger 源码

二、Swagger Editor

1. Swagger Editor 简介

编辑工具：Swagger Editor，页面如下图
它能提供语法高亮、自动补全、及时预览等功能
使用 Swagger 编辑器需要编写 yaml 文件，生成 API 接口文件。只要在给定的 yaml 文件，修改我们需要修改的部分，然后点击上方的 [Generate Server] 即可生成服务端代码， [Generate Client] 可以生成客户端代码，其中的 index.html 打开后是 API 可视化的页面
以编写服务端代码为例，之后需要往其中填充与前端交互的逻辑，以及完成配置数据库等对后端的操作

2. 下载安装

① 在线版

Swagger Editor 可在任何 Web 浏览器中使用

② Windows 本地

首先需要安装 node 和 npm。你可以在 cmd 命令行看到你的安装信息。使用命令 node -v 和 npm -v，可以用来查看版本信息。
具体 nodejs 的安装过程可以参考笔者的另一篇文章如何安装前后端分离的项目（安装 node.js 和 golang）
安装后，还需要安装 http-server。使用命令 npm install -g http-server
接着去 Swagger Editor官网下载源码
下载完成后，从命令行中进入 http-server 的安装目录，也就是 npm 包下载的位置
最后将 swagger editor 服务启动起来，启动成功后，在浏览器中输入 127.0.0.1:8081 就可以看到下面的界面

3. 具体使用步骤

① 准备工作

前后端开发者之间设计并规定好 API，之后使用 Swagger 渲染 API 文档和生成 go-server 和 vue-client
前后端分离进行开发，双方都根据 API 文档的规范进行 API 实现以及调用。前端使用 Vue.js 框架开发，后端使用 Swagger 生成的 go-server 进行进一步的开发

② 编写 yaml

yaml 例子

swagger: "2.0"
info:
  description: "This is a sample server Petstore server.  You can find out more about     Swagger at [http://swagger.io](http://swagger.io) or on [irc.freenode.net, #swagger](http://swagger.io/irc/).      For this sample, you can use the api key `special-key` to test the authorization     filters."
  version: "1.0.0"
  title: "Swagger Petstore"
  termsOfService: "http://swagger.io/terms/"
  contact:
    email: "apiteam@swagger.io"
  license:
    name: "Apache 2.0"
    url: "http://www.apache.org/licenses/LICENSE-2.0.html"
host: "petstore.swagger.io"
basePath: "/v2"

schemes:
 - "https"
 - "http"
paths:{}

首行通过 swagger 属性表明 OpenAPI 规范的版本
info 属性是 API 的描述信息
host, basePath, schemes 分别是 API 的主机名，相对于host的路径和 API 传输协议
path 先用 yaml 空对象 {} 占位，之后可以填充

  /user/login:
    get:
      tags:
      - "user"
      summary: "Logs user into the system"
      description: ""
      operationId: "loginUser"
      produces:
      - "application/xml"
      - "application/json"
      parameters:
      - name: "username"
        in: "query"
        description: "The user name for login"
        required: true
        type: "string"
        x-exportParamName: "Username"
      - name: "password"
        in: "query"
        description: "The password for login in clear text"
        required: true
        type: "string"
        x-exportParamName: "Password"
      responses:
        "200":
          description: "successful operation"
          headers:
            X-Rate-Limit:
              type: "integer"
              format: "int32"
              description: "calls per hour allowed by the user"
            X-Expires-After:
              type: "string"
              format: "date-time"
              description: "date in UTC when token expires"
          schema:
            type: "string"
        "400":
          description: "Invalid username/password supplied"

填充完 path 后可以看到效果
我们添加一个 /user 的路径，用来访问一组用户信息。在路径中可以添加任意的 HTTP 动词来操作所需要的资源。比如 GET, POST, PUT, DELETE
接着用 responses 定义响应类型，可以在 responses 中添加任意的 HTTP 状态码
接着定义 Get /user/login 这个接口的响应内容，通过 schema 属性来描述具体的返回内容。
有了响应内容，当然应该也会有请求参数，增加参数，我们需要使用 parameters 属性
in 属性指定参数位置
definitions可以用来定义常用的内容，定义完成后，我们可以使用 reference 属性来引用，也就是 $ref

 post:
      tags:
      - "user"
      summary: "Create user"
      description: "This can only be done by the logged in user."
      operationId: "createUser"
      produces:
      - "application/xml"
      - "application/json"
      parameters:
      - in: "body"
        name: "body"
        description: "Created user object"
        required: true
        schema:
          $ref: "#/definitions/User"
        x-exportParamName: "Body"

③ 服务端代码

下面主要介绍从 Swagger Editor Generate Server 后得到的服务端代码目录 go-server
go-server 文件结构

├── api
│   └── swagger.yaml
├── go
│   ├── api_XXX.go
│   ├── logger.go
│   ├── model_XXX.go
│   ├── README.md
│   └── routers.go
└── main.go

go 文件夹下是对以下各个功能的实现

api_XX.go： XXX API 的实现
model_XX.go：对象模型的实现
route.go：路由
logger.go：日志输出

1）api_XX.go

函数实现 API 的功能，例如创建 User

func CreateUser(w http.ResponseWriter, r *http.Request) {
	w.Header().Set("Content-Type", "application/json; charset=UTF-8")
	w.WriteHeader(http.StatusOK)
}

2）model_XX.go

包含某个对象的所有成员变量

type User struct {

	Id int64 `json:"id,omitempty"`

	Username string `json:"username,omitempty"`

	FirstName string `json:"firstName,omitempty"`

	LastName string `json:"lastName,omitempty"`

	Email string `json:"email,omitempty"`

	Password string `json:"password,omitempty"`

	Phone string `json:"phone,omitempty"`

	// User Status
	UserStatus int32 `json:"userStatus,omitempty"`
}

3）logger.go

标准日志输出，包括方法，请求 URI，名字和时间

func Logger(inner http.Handler, name string) http.Handler {
    return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
        start := time.Now()

        inner.ServeHTTP(w, r)

        log.Printf(
            "%s %s %s %s",
            r.Method,
            r.RequestURI,
            name,
            time.Since(start),
        )
    })
}

4） route.go

Route 存储路由的基本信息，是由 swagger 自动生成的服务端代码，主要用于连接对应的 API 和实现它们的函数

type Route struct {
	Name        string
	Method      string
	Pattern     string
	HandlerFunc http.HandlerFunc
}

type Routes []Route

func NewRouter() *mux.Router {
	router := mux.NewRouter().StrictSlash(true)
	for _, route := range routes {
		var handler http.Handler
		handler = route.HandlerFunc
		handler = Logger(handler, route.Name)

		router.
			Methods(route.Method).
			Path(route.Pattern).
			Name(route.Name).
			Handler(handler)
	}

	return router
}

func Index(w http.ResponseWriter, r *http.Request) {
	fmt.Fprintf(w, "Hello World!")
}

var routes = Routes{
	Route{
		"Index",
		"GET",
		"/v2/",
		Index,
	},
	……
}