From 10c505ccab9164bf4bbabb9e73515c5ec10516ea Mon Sep 17 00:00:00 2001 From: Elmer Bulthuis Date: Tue, 3 Jun 2025 16:08:35 +0700 Subject: [PATCH 1/2] some readme --- README.md | 36 +++++++++++++- packages/npm/skiffa-generator/README.md | 63 +++++++++++++++++++++++++ 2 files changed, 98 insertions(+), 1 deletion(-) create mode 100644 packages/npm/skiffa-generator/README.md diff --git a/README.md b/README.md index dfd71e2..d29ff6b 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ # Skiffa -With love from [Scheveningen](https://www.youtube.com/live/DaG5JReOYEw?si=Jbe5P41pGgW92AZO)! +With love from [Scheveningen](https://www.youtube.com/live/DaG5JReOYEw)! We love our early bird sponsors! @@ -9,6 +9,40 @@ We love our early bird sponsors! [TokenMe](https://token-me.com/) [Husense](https://www.husense.io/) +## What is it + +Skiffa generator is a code generator that takes an OpenApi schema and generates code in many languages. It is able to generate clients and servers, types and validators and even mocks and tests. + +Check out the generator for you favorite language + +- [TypeScript](./packages/npm/skiffa-generator/REAMDE.md) + +## Use cases + +Because Skiffa is able to generate both client _and_ server code from an OpenApi schema it may be used for a number of things! Here are a few example use cases + +### Client (sdk) generation + +Use Skiffa to generate SDK's for your api and distribute them via the language's registry. Your client is able to use your system by simply installing the SDK in the language of their choice. All of this is generated from one single OpenApi specification that is also ues to generate documentation and even the server code. + +### Server generation + +Generate a server from an OpenApi specification so you can use this specification as a contract. The server will follow the specification so you have complete control over things like backwards compatibility. + +### Migration + +If you have an existing system that outputs an OpenApi specification and you want to migrate to another programming language, you can use the specification to generate a server in the new language. Now all that is left is to implement the functionality. + +Many Skiffa clients do this but first using the generated Skiffa client and pass through every operation from the service that we migrate away from. So initially the server is a proxy. Then the system if migrated on operation at a time. + +### Testing + +Testing integrations with a third party may be difficult. Skiffa can solve that. Simply create a server from the third party's OpenApi specification and you have a mocked server that is ideal for testing. + +### Many more! + +There are many more, some very specific use cases, if you have an intersting one. Please let us know! + ## Installing First, install dependencies via `npm install`. diff --git a/packages/npm/skiffa-generator/README.md b/packages/npm/skiffa-generator/README.md new file mode 100644 index 0000000..b62370a --- /dev/null +++ b/packages/npm/skiffa-generator/README.md @@ -0,0 +1,63 @@ +# Skiffa generator, TypeScript edition + +Skiffa generator is a code generator that takes an OpenApi schema and generates client and server code in TypeScript. The server can be used in a node environment without a lot of boilerplate. The client works in node and the browser. The client and server are fully types and support streaming. + +Types and validators are also generated (via [JsonSchema42](https://github.com/LuvDaSun/JsonSchema42)) and automatically applied so you can be sure that the data that you receive is exactly what you specified in the schema. + +Tests are generated from the examples in the specification and from mocks that are also generated from the schemas in the specification. + +With Skiffa you can take an api like this: + +```yaml +openapi: 3.0.0 + +info: + title: hw-api + description: Hello World + version: 0.1.0 + +paths: + /world: + get: + operationId: get-world + summary: get's information from the world + responses: + "200": + description: Ok + content: + "application/json": + schema: + type: object + required: + - message + properties: + message: + type: string + minLength: 1 +``` + +And turn it into a (tree shakable!) client that can be used like this: + +```ts +import * as api from "hw-api"; + +const { message } = await api.client.getWorld(); + +console.log(message); +``` + +Or, create and run a server like this: + +```ts +import * as api from "hw-api"; + +const server = new api.server.Server(); + +server.registerGetWorldOperation(async () => { + return { + message: "Hello, World!", + }; +}); + +api.lib.listen(server, { port: 8080 }); +``` From 937c5e4f843b45e1ad5e09623c8a2b94b8daabed Mon Sep 17 00:00:00 2001 From: Elmer Bulthuis Date: Tue, 3 Jun 2025 16:11:00 +0700 Subject: [PATCH 2/2] fix spelling --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index d29ff6b..a335a82 100644 --- a/README.md +++ b/README.md @@ -41,7 +41,7 @@ Testing integrations with a third party may be difficult. Skiffa can solve that. ### Many more! -There are many more, some very specific use cases, if you have an intersting one. Please let us know! +There are many more, some very specific use cases, if you have an interesting one. Please let us know! ## Installing