Categorygithub.com/jinzhenj/api1
module
0.2.2
Repository: https://github.com/jinzhenj/api1.git
Documentation: pkg.go.dev
Overview
Versions
1
Dependencies
0
Dependents
0
Files
0

# README

api1 (api first)

Quick Install

go install github.com/jinzhenj/api1/cmd/[email protected]

api1 is:

  1. An api definition language
  2. An api doc generating tool (openapi for now)
  3. An api code generating tool (golang server code for now)

api1 definition language specification

Api definition contains 2 parts:

  1. function definitions (which can be invoked)
  2. type/struct definitions (as input/output types of these functions)

Most programming languages provides these 2 abilities.

api1(api first) 是一个代码和文档生成工具。这个工具会从 *.api 文件中读取api定义，并支持生成：

  • 函数声明中用到的结构体类型定义（含输入参数类型或返回类型）

本文档将详细介绍 *.api 文件的语法规则。作为api1的使用者，请务必仔细阅读本文档。

*.api 文件语法的设计原则

  1. 尽量使用各种语言中常见的数据类型和语法特征。
  2. 会在简单易用和强大的定义能力中寻求平衡点，仅以满足常见api定义需求为目标。

参考语言

  • golang
  • javascript/typescript
  • kotlin
  • graphql
  • protobuf

Built-in Scalar Types

apigolangjavascripttypescriptopenapipython
intint64numbernumberintegerint
floatfloat64numbernumbernumberfloat
stringstringstringstringstringstr
booleanboolbooleanbooleanbooleanbool
objectmapobjectobjectobjectdict
anyinterface{}-anyoneOf[]typing.Any

Custom Scalar Types

例子

scalar datetime

Real world scalar types

# @go.type string
# @openapi.type string
# @openapi.format password
scalar Password

# example: 2022-11-29T03:09:18.031Z
# @go.type time/Time
# @openapi.type string
# @openapi.format date-time
scalar Time

# example: 1669691224000
# @go.type int64
# @go.typeDef
# @openapi.type integer
scalar Timestamp

# example: 2006/01/02 15:04
# @go.type string
# @go.typeDef
# @openapi.type string
scalar TimeTillMinute

# @go.type *multipart.FileHeader
# @go.typePkg mime/multipart
# @openapi.type string
# @openapi.format binary
scalar MultipartFile

枚举类型

枚举类型在api定义中十分常见，枚举类型的定义语法如下：

例子：

enum ProtocolType {
  TCP
  UDP
}

枚举项使用自定义Value的例子：

enum Colour {
  RED = "red"
  GREEN = "green"
  BLUE = "blue"
}

枚举项使用数值型Value的例子：

enum Colour {
  RED = 1
  GREEN = 2
  BLUE = 3
}

结构体类型

结构体类型中包含明确的字段定义，每个字段的类型也都是明确的。 结构体类型的定义语法如下：

例子：

struct User {
  id: int
  name: string
  email: string
  admin: boolean
}

数组类型

基本类型、枚举类型、以及结构体类型，均可定义为数组类型。 定义数组类型的语法如下：

例子：

[string]
[ProtocolType]
[User]
[[int]]  # 数组的数据，即二维数组

类型可为空

当类型后面带有 ? 时，表示当前类型可为空。

例子：

string?    # 可为null的字符串
[string]?  # 可为null的字符串数组
[string?]  # 数组中的元素可为null

更多例子：

struct User {
  name: string
  address: string?
  phoneNumbers: [string]?
}

接口

接口中定义了可交互的方法（函数），该方法接受0～N个入参，返回0～1个出参。 参数类型可以是基本类型、枚举类型、结构体类型或数组类型。

接口类型的定义语法如下：

interface UserController {

  register(req: RegisterReq)

  login(req: LoginReq)

  getUserInfo(req: UserInfoReq): UserInfoResp

  listUsers(pageSize: int, pageNo: int): [User]
}

注释

以 # 符号来定义注释

语义注释

语义注释是注释的扩展，它类似SQL语言中的Hit，不以语法形式存在。 语义注释定例子如下：

interface UserController {

  # @route post /user/login
  login(req: LoginReq)
}

# @route get /another
# @go.package some/package
# @go.someAttr:json|
#   {
#     "a": 1,
#     "b": 2,
#   }
interface AnotherController {

}

Known Semantic Comments

@route

used for: Fun

Function is a rest route handler.

Example:

interface user {

  # @route get /users/:id
  getUser(id: int): User
}

@route.in

used for: Scalar

To specify the position a scalar type should be put in when using as a route param (instead of query param by default).

known values: body (consider support header & cookie in future.)

Example:

# @route.in body
scalar DataObject

interface data {

  # @route post /data/:id
  postData(id: int, data: DataObject): DataObject
}

@omitempty

used for: StructField

Field won't return if it is empty.

Example:

struct User {
  name: string

  # @omitempty
  address: string
}

@ignore

used for: StructField

Field won't return.

Example:

struct User {
  name: string

  # @ignore
  password: string
}

@go.type

used for: Scalar, StructField, Param, Fun

Specify golang type for scalar or typeRef.

Example:

# @go.type uint64
scalar Timestamp

struct User {
  
  # @go.type map[string]string
  properties: object
}

interface user {

  # @route get /users/:id/properties
  # @go.type map[string]string
  getProperties(id: int): object
 
  # @route put /users/:id/properties
  setProperties(
    id: int,

    # @go.type map[string]string
    properties: object
  )
}

@go.middleware

used for: Fun

Add middleware for golang route handler

Example:

interface TypeController {

  # @route get /types
  listTypes(): [Type]

  # @route put /types/:id
  # @go.middleware adminRequired
  modifyType(id: int, type: Type)
}

@go.validator

used for: StructField, Param

Add validator for field or param.

Example:

struct UserLoginRequest {
  # @go.validator: email
  email: string
  password: string
}

interface LoginController {

  # @route post /actions/checkUserExists
  checkUserExists(
    # @go.validator email
    email: string
  ): boolean
}

@go.tag

used for: StructField

Add struct tag for golang struct field.

Example:

struct User {
  # @go.tag gorm:"uniqueIndex"
  email: string
}

@go.package

@go.import

@ts.modifier

@deprecated

@default

@minimum & @maximum

@minLength & @maxLength

@form & @accept

# @go.type *multipart.FileHeader
# @go.typePkg mime/multipart
# @openapi.type string
# @openapi.format binary
scalar MultipartFile

# @form
struct UploadInfo {
  file: MultipartFile
  path: string
}

interface UploadApi {
  # @route post /actions/upload
  # @accept multipart/form-data
  doUpload(req: UploadInfo): object
}

与package相关的注释

与web api相关的注释

问题：

1、合法性检查 2、高亮 3、代码之间跳转

# Packages

No description provided by the author
No description provided by the author