Validation, serialization and documentation
- Dominant language
- TypeScript
- Stars
- 7
- Forks
- 5
- PR merge metrics
- No merged PRs in 30d
Description
# Actual Configuration
- AJV
- JSON Schema (>Draft 6)
- Fluent Schema
- OpenAPI 3.0
# Issues identified by our current implementation
- We have to describe our data multiple times (DTO, Schema)
- References are broken.
- They're pointing to an URI, this is usually used to point to a distant schema on another server, but we're using it to reference a local schema. Because of that, the Swagger page will try to fetch the schema on the URI and will have broken references.
- We can't easily get the content of a reference.
- Output validation takes too much time
- Not compliant with OpenAPI 3.0
- We can't namespace our components as we do with our definitions. Because of that, the Swagger page have broken components.
- `fastify.addSchema(...)` needs a parameter of type `unknown`
# Proposed Solution
## Refactor our current implementation
By renaming our references (https://json-schema.org/understanding-json-schema/structuring#schema-identification) and removing the namespaces.
## DTO to Schema
- Class Validator & Class Validator JSON Schema
- https://github.com/typestack/class-validator
- https://github.com/epiphone/class-validator-jsonschema
## Schema to DTO
> Also check https://fastify.dev/docs/latest/Reference/Type-Providers/
- TypeBox
- https://github.com/sinclairzx81/typebox
- Zod
- https://zod.dev/
- Optionally, have a look on https://trpc.io/
- Typed AJV
- https://github.com/keplr-team/typed-ajv
# Step 1 : Remove all refs
- [x] #1396
- [x] #1407
- [x] #1410
- [x] #1430
- [x] #1436
- [x] #1438
- [x] #1440
- [x] #1453
- [x] #1459
# Step 2 : Translate every routes to TypeBox
- [x] #1405
- [x] #1471
- [x] #1409
- [x] #1473
- [x] #1475
- [x] #1498
# Non-conventional API Routes
- [ ] `GET /items/flags/` to `GET /items/flags/types`
- [ ] https://github.com/graasp/graasp/issues/1342
- [ ] https://github.com/graasp/graasp/issues/1375
- [ ] MemberID Params must be showed as deprecated on Swagger Page
- [ ] `PATCH /items/short-links/:alias` allows modification to either alias or platform but not both. We also probably do not want to patch the platform anymore.
- [ ] Should we rename all `url` properties to `uri` so it matches the string format ?
- [ ] `POST` and `PATCH` of `/items` needs to be splitted in multiples routes for each type.
- [ ] `/item-memberships` needs to be rethinked
# Other related issues
- [ ] https://github.com/graasp/graasp/issues/1358
- [ ] Type the FastifySchema, so we force the use of Typebox. We could also check if it is possible to type the fastify instance
- [ ] Split the ErrorSchemaRef into more specific refs
- [ ] #1541
- [ ] Use TypeCompiler instead of Ajv validation in `validation.ts` files
# Continuous validation of the API
- [x] #1525
- We can use [Vacuum](https://quobix.com/vacuum/api/getting-started/) so we lint every issue of our open api by creating a script in `package.json`
- [x] #1528
- [x] #1536
Contributor guide
No contributing guide indexed for this repository
Assessment
This issue has not been assessed yet.