From 9df9c8699f5fd490a056ac68c91017ca91ca2313 Mon Sep 17 00:00:00 2001 From: jonaslagoni Date: Wed, 19 Nov 2025 21:53:46 +0100 Subject: [PATCH] fix docs --- README.md | 9 ++++--- docs/README.md | 3 ++- docs/inputs/asyncapi.md | 3 ++- docs/inputs/openapi.md | 55 ++--------------------------------------- docs/migrations/v0.md | 3 ++- 5 files changed, 13 insertions(+), 60 deletions(-) diff --git a/README.md b/README.md index bc7273f..a2b0c86 100644 --- a/README.md +++ b/README.md @@ -46,10 +46,11 @@ # Core Features -- 📃 Generate [payload](https://the-codegen-project.org/docs/generators/payloads), [headers](https://the-codegen-project.org/docs/generators/headers) or [parameter](https://the-codegen-project.org/docs/generators/parameters) representations from your AsyncAPI document (including Protobuf, RAML, OpenAPI Schema) or OpenAPI (Swagger 2.0, 3.0, and 3.1) -- 📊 Customize the output to your hearts desire -- 💫 Regenerate once the input changes -- 👀 Integrate it into any project (such as [Next.JS](./examples/typescript-nextjs), [TypeScript Libraries](./examples/typescript-library), you name it.) +- 📃 Generate [payloads](https://the-codegen-project.org/docs/generators/payloads), [headers](https://the-codegen-project.org/docs/generators/headers), [parameters](https://the-codegen-project.org/docs/generators/parameters), [protocol helpers](https://the-codegen-project.org/docs/generators/channels), [full clients](https://the-codegen-project.org/docs/generators/client), [models](https://the-codegen-project.org/docs/generators/models), [simple types](https://the-codegen-project.org/docs/generators/types), or all of the above from your [AsyncAPI v2 and v3](https://the-codegen-project.org/docs/inputs/asyncapi) +- 📃 Generate [payloads](https://the-codegen-project.org/docs/generators/payloads), [headers](https://the-codegen-project.org/docs/generators/headers), [parameters](https://the-codegen-project.org/docs/generators/parameters), [models](https://the-codegen-project.org/docs/generators/models), [simple types](https://the-codegen-project.org/docs/generators/types), or all of the above from your [Swagger 2.0, or OpenAPI 3.0, and 3.1](https://the-codegen-project.org/docs/inputs/openapi) +- 📃 Generate [models](https://the-codegen-project.org/docs/generators/models) or [completely customize it](https://the-codegen-project.org/docs/generators/custom) for [JSON Schema Draft-4, Draft-6 and Draft-7](https://the-codegen-project.org/docs/inputs/jsonschema) +- 📊 Every generator fully customizable to fit your hearts desire +- 👀 Integrate it into any project (Demos in [Next.JS](./examples/typescript-nextjs), [TypeScript Libraries](./examples/typescript-library)) - 💅 [Create custom generators to your use-case](https://the-codegen-project.org/docs/generators/custom) - 🗄️ Protocol agnostic generator ([NATS](https://the-codegen-project.org/docs/protocols/nats), [Kafka](https://the-codegen-project.org/docs/protocols/kafka), [MQTT](https://the-codegen-project.org/docs/protocols/mqtt), [AMQP](https://the-codegen-project.org/docs/protocols/amqp), [event-source](https://the-codegen-project.org/docs/protocols/eventsource), [HTTP Client](https://the-codegen-project.org/docs/protocols/http_client), [WebSocket](https://the-codegen-project.org/docs/protocols/websocket), read the [docs](https://the-codegen-project.org/docs#protocols) for the full list and information) - ⭐ And much more... diff --git a/docs/README.md b/docs/README.md index 7730ab4..35644e3 100644 --- a/docs/README.md +++ b/docs/README.md @@ -44,6 +44,7 @@ If there has been a decision about certain technical solutions it will be marked Each input has its own limitations, corner cases, and features; thus, each has separate documentation. - [AsyncAPI](./inputs/asyncapi.md) - [OpenAPI](./inputs/openapi.md) +- [JSON Schema](./inputs/jsonschema.md) ### Protocols Each protocol has its own limitations, corner cases, and features; thus, each has separate documentation. @@ -55,7 +56,7 @@ Each protocol has its own limitations, corner cases, and features; thus, each ha - [HTTP Client](./protocols/http_client.md) - [WebSocket client and server](./protocols/websocket.md) -### [Migrations](./contributing.md) +### [Migrations](./migrations/README.md) Get an overview of how to contribute to the project diff --git a/docs/inputs/asyncapi.md b/docs/inputs/asyncapi.md index f2db25a..85d229b 100644 --- a/docs/inputs/asyncapi.md +++ b/docs/inputs/asyncapi.md @@ -24,6 +24,7 @@ There is a lot of overlap with existing tooling, however the idea is to form the | [`channels`](../generators/channels.md) | ✅ | | [`client`](../generators/client.md) | ✅ | | [`custom`](../generators/custom.md) | ✅ | +| [`models`](../generators/custom.md) | ✅ | ## Basic AsyncAPI Document Structure @@ -920,4 +921,4 @@ Short answer: Use the `info.version` field in your AsyncAPI document and conside Long answer: It's hard to version APIs, there are tons of resources how to handle versioning of your API which is far beyond what we can offer here. ### Can I customize the generated code structure? -Yes, use the `x-the-codegen-project` extension properties to customize channel names, function mappings, and other generation aspects. If you want full control, use the [custom preset](../generators/custom.md) +Yes, use the `x-the-codegen-project` extension properties to customize channel names, function mappings, and other generation aspects or the configuration file [while taking a look at the different generators](../generators). diff --git a/docs/inputs/openapi.md b/docs/inputs/openapi.md index 2e5cb1b..eae4127 100644 --- a/docs/inputs/openapi.md +++ b/docs/inputs/openapi.md @@ -19,6 +19,7 @@ Input support; `openapi` | [`channels`](../generators/channels.md) | ❌ | | [`client`](../generators/client.md) | ❌ | | [`custom`](../generators/custom.md) | ✅ | +| [`models`](../generators/custom.md) | ✅ | ## Basic Usage @@ -59,66 +60,14 @@ Full support for OpenAPI 3.1 features including: - `if`/`then`/`else` conditionals - Enhanced `examples` support -### Validation and Error Handling - -The parser provides detailed validation errors: - -```typescript -// If validation fails, you'll get detailed error information -try { - const document = await loadOpenapi(context); -} catch (error) { - console.error('OpenAPI validation failed:', error.message); - // Error message includes line numbers and specific validation issues -} -``` - -## Examples - -### REST API Client Generation - -Generate a complete TypeScript client for your REST API: - -```json -{ - "inputType": "openapi", - "inputPath": "./api/openapi.yaml", - "language": "typescript", - "generators": [ ] -} -``` - -## Best Practices - -1. **Schema Organization**: Use `$ref` to organize complex schemas into separate files -2. **Validation**: Always validate your OpenAPI documents before generation -3. **Versioning**: Include version information in your API specifications -4. **Documentation**: Use `description` fields extensively for better generated code -5. **Examples**: Provide examples in your schemas for better understanding - ## Troubleshooting -### Common Issues - -1. **Invalid $ref**: Ensure all referenced files exist and are accessible -2. **Schema Validation**: Check that your OpenAPI document follows the specification -3. **File Format**: Verify that YAML/JSON syntax is correct -4. **Circular References**: Avoid circular `$ref` dependencies - ## FAQ ### Can I use both OpenAPI and AsyncAPI in the same project? Yes! You can have separate configuration files for each input type and generate code to different output directories. -### What's the difference between OpenAPI 3.0 and 3.1? - -OpenAPI 3.1 is fully compatible with JSON Schema 2020-12 and includes additional features like `const`, conditional schemas, and enhanced examples support. - -### How do I handle authentication in generated clients? - -Define security schemes in your OpenAPI document, and the generated client code will include appropriate authentication handling. - ### Can I customize the generated code? -Yes, use the custom generator preset to create your own templates and generation logic. \ No newline at end of file +Yes, use the [custom generator](../generators/custom) preset to create your own generation logic. \ No newline at end of file diff --git a/docs/migrations/v0.md b/docs/migrations/v0.md index 78c83ba..f7d8f9b 100644 --- a/docs/migrations/v0.md +++ b/docs/migrations/v0.md @@ -58,8 +58,9 @@ const subscriber = await jetStreamPullSubscribeToReceiveUserSignedup({ }); ``` +## Breaking Changes 0.55.1 - +We upgraded the AsyncAPI Modelina dependency to the `next` version so for the next few versions it will contain breaking changes as we continue to improve the tool.