manyleb 0.0.2

Manyleb (Welsh for 'specification') is a DSL designed for specifying HTTP APIs in a concise but precise manner.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121

# Manyleb

Manyleb (Welsh for "specification") is a DSL designed for specifying HTTP APIs in a concise but precise manner.

## Writing Specifications

### Basic Structure

A Manyleb specification consists of some metadata, followed by object definitions, followed by route definitions.

```manyleb
version "1.0.0"
title "Sample API"
description "This is a sample API specification."

object User {
    prop id   string   "Unique identifier for the user"
    prop name string   "Name of the user"
    prop age  ?integer "Age of the user"
}

route get "/users" {
    description "Retrieve a list of users"

    tag "Users"

    response 200 []User
}

route get "/users/:id" {
    description "Retrieve a specific user by ID"

    tag "Users"

    response 200 User
    response 404
}
```

### Metadata

Metadata fields include `version`, `title`, and `description`.

### Types

Types can be primitive, composite, or user-defined objects.

Primitive types are:

- `string` / `str`
- `integer` / `int`
- `boolean` / `bool`
- `float`
- `null`

Composite types are:

- Arrays: `[]typename`
- Maps: `<tkey, tvalue>`

User defined objects are declared using the `object` keyword, and referenced in types by their name, e.g., `User`.

Types can be marked as optional by prefixing them with `?`, e.g., `?string`.

### Objects

Objects are defined using the `object` keyword, followed by properties.

Properties follow the format `prop name type "description"`.

### Routes

Routes are defined using the `route` keyword, followed by the HTTP method and path.

Routes can have descriptions, tags, params, query params, and multiple responses.

Routes follow the format:

```manyleb
route method "/path" {
    description "Route description"

    tag "TagName"

    param name type "description"

    query name type "description"

    response status_code type
}
```

## CLI Usage

### Format Command

To format a Manyleb specification file, use the following command:

```bash
manyleb format path/to/spec.manyleb
```

### Verify Command

To verify a Manyleb specification file for correctness, use the following command:

```bash
manyleb verify path/to/spec.manyleb
```

### Docs Command

To generate documentation from a Manyleb specification file, use the following command:

```bash
manyleb docs path/to/spec.manyleb path/to/output.md
```

## License

Manyleb is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.