You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: README.md
+2-177Lines changed: 2 additions & 177 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -10,184 +10,9 @@ The goal of this project was to automate a lot of the hassle of maintaining Open
10
10
11
11
</br>
12
12
13
-
## ⚖️ Tradeoffs
13
+
## 🔗 Documentation
14
14
15
-
As mentioned in the [✨ Features & Quirks](#-features--quirks) section, Schematica is a small, local, on-disk solution for collaboration between backend and frontend teams.
16
-
17
-
Everything is designed to be very simple and manual — which is the most important tradeoff for this solution. I'm simply not a fan of complicated solutions for simple problems. I believe Schematica's simplistic approach to collaboration, though burdensome in a few cases, is the ideal solution for a tool meant to stay out of the way.
18
-
19
-
</br>
20
-
21
-
## ✨ Features & Quirks
22
-
23
-
This section is very important. Please read it to understand what Schematica is about.
24
-
25
-
</br>
26
-
27
-
### 💾 Local-First
28
-
29
-
Schematica allows you to create a so-called “Project,” which is, at its core, an OpenAPI Specification JSON file.
30
-
31
-
Each project is split into two JSON files:
32
-
33
-
-**Metadata**: contains information such as who last edited project metadata (description, base URL, etc.)
34
-
-**OpenAPI**: a slightly customized OpenAPI JSON file containing endpoint metadata via the `x-*` property
35
-
36
-
Both files are stored locally in the Express.js backend (`/app_data/projects`). This is because Schematica was designed as an internal tool without any dependency on external systems. It’s designed to be a very simple in-house tool that can be spun up quickly in any environment — no need for a database at all.
37
-
38
-
The same direct on-disk design applies to authentication. In `app_data/users`, there is a `users-db.json` file containing user data. Here's a sample:
Creating users and their passwords is a matter of defining them manually in this JSON file and running `npm run prepare` to hash their passwords. While creating a user initially, you must store their password as plain text in the `"password"` field and then run the _prepare_ script to hash them. It will skip already hashed users.
73
-
74
-
⚠️ Important: This script modifies the original `users-db.json` file. Back up your user file before running it.
75
-
76
-
</br>
77
-
78
-
### 🌀 CURL Conversion
79
-
80
-
Schematica allows the backend team to simply paste the CURL request for an endpoint into the CURL input box. This automatically adds the request to the OpenAPI JSON file and attempts to generate schemas for the inputs as well.
81
-
82
-
These CURL requests are also available for each endpoint via a "**Copy CURL**" button, so the frontend team can easily test them in Postman (or any other HTTP GUI client).
83
-
84
-
</br>
85
-
86
-
### 📂 Endpoints Details
87
-
88
-
Schematica lets you add detailed metadata (headers, query params, path params, etc.) to your endpoints. This includes:
89
-
90
-
- Request bodies
91
-
- Responses
92
-
- Developer notes
93
-
- Auto-generated schemas for inputs/outputs via sample payloads
94
-
95
-
</br>
96
-
97
-
### 📤 Postman Export
98
-
99
-
The entire project can be exported as a **Postman v2.1** file — useful when either the frontend or backend team wants to share a standardized version of the API project.
100
-
101
-
</br>
102
-
103
-
### 📦 OpenAPI Export
104
-
105
-
The full project can also be downloaded as an OpenAPI JSON file. The exported file strips out any non-standard (i.e. `x-*`) properties, leaving a clean OpenAPI-compatible document.
106
-
107
-
</br>
108
-
109
-
### 📝 OpenAPI Editor
110
-
111
-
The OpenAPI JSON file is directly editable using the Monaco editor (VSCode's editor engine). This is especially handy for bulk edits or importing an entire OpenAPI document into a new Schematica project.
112
-
113
-
Note: Upon import, the `components` section is flattened and inlined into the individual endpoints, and the original `components` section is removed.
114
-
115
-
</br>
116
-
117
-
### 🧠 Optimistic Concurrency Control
118
-
119
-
120
-
In collaborative environments, multiple users may be editing the same project simultaneously. Schematica uses Optimistic Concurrency Control to handle conflicts. If you're editing an outdated version of the project, you'll be prompted with three options:
121
-
122
-
- ✅ Force overwrite your changes
123
-
- 🔄 Discard your changes and update the form with the latest version
124
-
- ⏳ Cancel the edit operation (copying your changes before deciding to not lose them)
125
-
126
-
</br>
127
-
128
-
### 🕵️♂️ Blame
129
-
130
-
Each endpoint includes two important metadata:
131
-
132
-
- Who originally added the endpoint and when
133
-
- Who last edited the endpoint and when
134
-
135
-
This makes it easier to audit changes and track down the source of bugs or regressions.
136
-
137
-
**NOTE**: If you edit the OpenAPI file directly via the Monaco editor, Schematica will attempt a smart merge and update endpoint metadata accordingly
138
-
139
-
</br>
140
-
141
-
### 🗒️ Notes
142
-
143
-
The users with `write` access (see `app_data/users/users-db.json`), apart from being able to add endpoints, etc., can add notes to API endpoints. This is NOT designed to provide a conversation between teams, but for sharing important context or edge cases regarding an endpoint.
144
-
145
-
</br>
146
-
147
-
### 🔗 Related Links
148
-
149
-
Each project can include a set of related links (e.g. GitLab milestones, Slack messages, etc.) displayed as buttons in the UI.
150
-
151
-
</br>
152
-
153
-
## 🛠️ Build & Customize
154
-
155
-
To customize Schematica for your team or company:
156
-
157
-
1. Edit the basic values in the [`.env`](./.env) (both frontend and backend).
158
-
2. clone the [frontend repository](https://github.com/Amir-Zouerami/schematica-frontend) and the [backend repository](https://github.com/Amir-Zouerami/schematica-backend) placing them side by side in a folder.
159
-
160
-
```bash
161
-
# In both frontend/ and backend/ directories
162
-
npm install
163
-
```
164
-
165
-
3. In the frontend repo, run:
166
-
167
-
```bash
168
-
npm run build
169
-
```
170
-
This will generate a production build and automatically move it to the backend's `/public` folder, thanks to the [Vite Config File](./vite.config.ts) file.
171
-
172
-
173
-
⚠️ **WARNING**: Two `wasm` files (`tree-sitter.wasm` and `tree-sitter-bash.wasm`) are required to be present in the backend's `public` folder. They are used by the [curlconverter](https://www.npmjs.com/package/curlconverter) package and must always be available for static serving.
174
-
175
-
</br>
176
-
177
-
## 🚧 Disclaimer
178
-
179
-
This project was built as a personal/internal tool. It works great for its intended use — a local-first, zero-dependency API documentation and collaboration system.
180
-
181
-
However, if you plan to run it in production or expose it publicly:
182
-
183
-
- Harden the server
184
-
- Add much more extensive logging
185
-
- Use a real database
186
-
- Implement proper auth flows
187
-
188
-
</br>
189
-
190
-
## 🔗 Related Repositories
15
+
For a full documentation please visit the repository containing the backend code:
0 commit comments