Skip to content

Commit 81951b6

Browse files
jaronniejaronnie
committed
fix(templates): update guide
1 parent 21243e5 commit 81951b6

10 files changed

Lines changed: 543 additions & 319 deletions

File tree

‎embedded/api/guide.en.md‎

Lines changed: 171 additions & 37 deletions
Original file line numberDiff line numberDiff line change
@@ -1,61 +1,195 @@
1-
# API Service Template
1+
# API Service Template Guide
2+
3+
## Table of Contents
4+
5+
- [Overview](#overview)
6+
- [API Definition](#api-definition)
7+
- [API Field Validation](#api-field-validation)
8+
- [Group types folder by go_package](#group-types-folder-by-go_package)
9+
- [Merge handlers of the same group into one file](#merge-handlers-of-the-same-group-into-one-file)
10+
- [Common Commands](#common-commands)
11+
- [Add API Files](#add-api-files)
12+
- [Generate Code](#generate-code)
13+
- [Generate Swagger Documentation](#generate-swagger-documentation)
14+
- [Project Structure](#project-structure)
15+
- [Related Resources](#related-resources)
16+
17+
## Overview
18+
19+
API is a domain-specific language developed by go-zero (hereinafter referred to as API language or API description language), designed to implement a human-friendly basic description language for generating HTTP services.
20+
21+
jzero has extended the API syntax with the following features:
22+
23+
- `go_package`: Generate go types in the defined package, supporting duplicate type names across different API files, consistent with `go_package` in proto
24+
- `compact_handler`: Generate handlers for the same route group in a single file, reducing the number of files, consistent with the proto server module
25+
26+
## API Definition
27+
28+
```api
29+
info (
30+
// Define go_package: folder location for generated go types
31+
go_package: "user"
32+
)
33+
34+
type User {
35+
Id int `json:"id"`
36+
Username string `json:"username"`
37+
}
38+
39+
type PageRequest {
40+
Page int `form:"page"`
41+
Size int `form:"size"`
42+
Username string `form:"username,optional"` // Filter parameter, optional
43+
}
44+
45+
type PageResponse {
46+
Total uint64 `json:"total"` // Total
47+
List []User `json:"list"` // Paginated data
48+
}
49+
50+
type UpdateRequest {
51+
Id int `path:"id"`
52+
Username string `json:"username"`
53+
}
54+
55+
type UpdateResponse {}
56+
57+
@server (
58+
prefix: /api/user // Route prefix
59+
group: user // Handler/logic folder location
60+
jwt: JwtAuth // Enable jwt authentication
61+
middleware: AuthX // Middleware for this route group
62+
compact_handler: true // Merge handlers of this group into one file
63+
)
64+
service simpleapi {
65+
@doc "User Pagination"
66+
@handler Page
67+
get /page (PageRequest) returns (PageResponse)
68+
69+
@doc "Update User"
70+
@handler Update
71+
post /update (UpdateRequest) returns (UpdateResponse)
72+
}
73+
```
74+
75+
Corresponding curl commands:
276

3-
Build RESTful API services with automatic Swagger documentation generation.
77+
```bash
78+
# User pagination endpoint
79+
curl -X GET "http://localhost:8080/api/user/page?page=1&size=10&username=test" \
80+
-H "Authorization: Bearer "
81+
82+
# Update user endpoint
83+
curl -X POST "http://localhost:8080/api/user/update/123" \
84+
-H "Content-Type: application/json" \
85+
-H "Authorization: Bearer " \
86+
-d '{"username": "new_username"}'
87+
```
488

5-
## Features
89+
## API Field Validation
690

7-
- Auto-generated Swagger UI accessible at `/swagger`
8-
- RESTful API structure with best practices
9-
- Request/response model validation
10-
- Optional Redis caching support
11-
- Database ORM integration
91+
> jzero integrates https://github.com/go-playground/validator for field validation by default
1292
13-
## Creating a New Project
93+
```api
94+
syntax = "v1"
1495
15-
```bash
16-
jzero new my-api --frame api
17-
cd my-api
18-
jzero run
96+
type CreateRequest {
97+
Name string `json:"name" validate:"gte=2,lte=30"` // Name
98+
}
1999
```
20100

21-
After starting the service, visit http://localhost:8001/swagger to view the interactive API documentation.
101+
## Group types folder by go_package
22102

23-
## Optional Features
103+
The go_package option, referenced from proto files, can group generated message structures. Similarly in API files, the go_package option can group generated type structures.
24104

25-
You can enable additional features when creating the project:
105+
Two major advantages:
26106

27-
```bash
28-
# Enable model validation
29-
jzero new my-api --frame api --feature=model
107+
1. Avoid explosion of default generated types/types.go
108+
2. Improve development experience, type names in different groups won't conflict
30109

31-
# Enable Redis caching
32-
jzero new my-api --frame api --feature=redis
110+
```api
111+
syntax = "v1"
33112
34-
# Enable both model and Redis
35-
jzero new my-api --frame api --feature=model+redis
113+
info (
114+
go_package: "version"
115+
)
116+
```
36117

37-
# Enable cache
38-
jzero new my-api --frame api --feature=cache
118+
## Merge handlers of the same group into one file
119+
120+
```api
121+
@server (
122+
prefix: /api/v1
123+
group: system/user
124+
compact_handler: true
125+
)
126+
service simpleapi {
127+
@handler GetUserHandler
128+
get /system/user/getUser (GetUserRequest) returns (GetUserResponse)
129+
130+
@handler DeleteUserHandler
131+
get /system/user/deleteUser (DeleteUserRequest) returns (DeleteUserResponse)
132+
}
39133
```
40134

41-
## Project Structure
135+
## Common Commands
136+
137+
### Add API Files
138+
139+
Add api files in the desc/api folder:
140+
141+
```bash
142+
# group is test
143+
jzero add api test
42144

145+
# group is test/test1
146+
jzero add api test/test1
43147
```
44-
my-api/
45-
├── api/ # API handlers
46-
├── model/ # Data models (if enabled)
47-
├── internal/ # Internal packages
48-
└── main.go # Application entry point
148+
149+
### Generate Code
150+
151+
```bash
152+
# Generate service code
153+
jzero gen
154+
155+
# Generate based on changed files
156+
jzero gen --git-change
157+
158+
# Generate by specifying description directory or file
159+
jzero gen --desc desc/
160+
jzero gen --desc desc/api/user.api
49161
```
50162

51-
## Development
163+
### Generate Swagger Documentation
52164

53165
```bash
54-
# Run the development server
55-
jzero run
166+
# Generate Swagger UI documentation
167+
jzero gen swagger
56168

57-
# Build for production
58-
jzero build
169+
# Access in browser
170+
# GET /swagger/
59171
```
60172

61-
The Swagger documentation will automatically update based on your API definitions.
173+
## Project Structure
174+
175+
```
176+
.
177+
├── desc/ # Description files
178+
│ └── api/ # API description files
179+
│ └── user.api # User service API definition
180+
├── internal/
181+
│ ├── handler/ # HTTP handlers
182+
│ ├── logic/ # Business logic
183+
│ ├── svc/ # Service context
184+
│ ├── types/ # Type definitions
185+
│ └── middleware/ # Middleware
186+
└── cmd/
187+
└── server.go # Service entry point
188+
```
189+
190+
## Related Resources
191+
192+
- [API Guide](https://docs.jzero.io/guide/api.html)
193+
- [Add Command](https://docs.jzero.io/getting-started/add.html)
194+
- [Gen Command](https://docs.jzero.io/getting-started/gen.html)
195+
- [Swagger Generation](https://docs.jzero.io/getting-started/genclient.html)

0 commit comments

Comments
 (0)