openapi3-framworks-compare/go/goa_example/design/design.go

package design

import . "goa.design/goa/v3/dsl"

// 描述一个API的基本信息
var _ = API("Example Service", func() {
	Title("A Goa Example Service")
	Description("HTTP service for test")
	Server("host", func() {
		Host("localhost", func() { URI("http://localhost:8088") })
		Host("integration", func() { URI("http://localhost:8088") })
	})
})

// JWTAuth 描述了一个security scheme使用JWT tokens.
var JWTAuth = JWTSecurity("jwt", func() {
	Description(`Secures endpoint by requiring a valid JWT token retrieved via the signin endpoint. Supports scopes "api:read" and "api:write".`)
})

// BasicAuth 描述了一个security scheme使用basic authentication.
var BasicAuth = BasicAuthSecurity("basic", func() {
	Description("Basic authentication used to authenticate security principal during signin")
})

// Creds 描述了一个Json对象，包含3个字段
var Creds = Type("Creds", func() {
	Field(1, "jwt", String, "JWT token", func() {
		Example("eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiYWRtaW4iOnRydWV9.TJVA95OrM7E2cBab30RMHrHDcEfxjoYZgeFONFh7HgQ")
	})
	Field(2, "api_key", String, "API Key", func() {
		Example("abcdef12345")
	})
	Field(3, "oauth_token", String, "OAuth2 token", func() {
		Example("eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiYWRtaW4iOnRydWV9.TJVA95OrM7E2cBab30RMHrHDcEfxjoYZgeFONFh7HgQ")
	})
	Required("jwt", "api_key", "oauth_token")
})

// 使用Service描述一个服务
var _ = Service("Service1", func() {
	// 服务的描述信息
	Description("The secured service exposes endpoints that require valid authorization credentials.")
	// 该服务可能出现的异常情况
	Error("unauthorized", String, "Credentials are invalid")

	// 描述本服务全局可能可能返回的异常情况的状态码
	HTTP(func() {
		// 会匹配Error中描述的unauthorized
		Response("unauthorized", StatusUnauthorized)
	})
	GRPC(func() {
		Response("unauthorized", CodeUnauthenticated)
	})

	// 使用Method描述一个具体的请求(Operation)或grpc方法
	Method("signin", func() {
		// 本方法使用BasicAuth进行认证
		Security(BasicAuth)
		// 使用Payload描述请求的参数信息(Parameters)
		// 如下描述了一个简单的包含了两个参数的请求
		Payload(func() {
			Description("Credentials used to authenticate to retrieve JWT token")
			UsernameField(1, "username", String, "Username used to perform signin", func() {
				Example("user")
			})
			PasswordField(2, "password", String, "Password used to perform signin", func() {
				Example("password")
			})
			Required("username", "password")
		})
		// 接口正常时的返回结果
		Result(Creds)
		// HTTP描述
		HTTP(func() {
			// 使用POST方法请求，这个时候Payload会以JSON Body的形式传入
			POST("/signin")
			// 接口返回时可能出现的状态码
			Response(StatusOK)
			Response(StatusBadRequest)
		})
		// GRPC描述
		GRPC(func() {
			// 接口返回时可能出现的状态码
			Response(CodeOK)
			Response(CodeInternal)
		})
	})

	Method("secure", func() {
		Description("这是一个需要JWT认证的接口")
		// 定义使用JWT 认证
		Security(JWTAuth)
		// Payload信息
		Payload(func() {
			Field(1, "fail", Boolean, func() {
				Description("Whether to force auth failure even with a valid JWT")
			})
			// 特殊的Field，用于让Goa识别该字段为Token，且在Header中
			TokenField(2, "token", String, func() {
				Description("JWT used for authentication")
			})
			Required("token")
		})

		// 返回的类型为字符串
		Result(String)

		HTTP(func() {
			GET("/secure")
			Response(StatusOK)
		})

		GRPC(func() {
			Response(CodeOK)
		})
	})
})