feat: add openapi support (#218)

Author: jonaslagoni

README.md

@@ -46,7 +46,7 @@
 </table>
 
 # 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)
+- 📃 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.)

docs/README.md

@@ -43,6 +43,7 @@ If there has been a decision about certain technical solutions it will be marked
 ### Inputs
 Each input has its own limitations, corner cases, and features; thus, each has separate documentation.
 - [AsyncAPI](./inputs/asyncapi.md)
+- [OpenAPI](./inputs/openapi.md)
 
 ### Protocols
 Each protocol has its own limitations, corner cases, and features; thus, each has separate documentation.
@@ -68,3 +69,4 @@ Get an overview of how to contribute to the project
 
 
 
+

docs/contributing.md

@@ -153,4 +153,5 @@ Prefix that follows specification is not enough though. Remember that the title
 
 
 
+
 

docs/generators/README.md

@@ -20,6 +20,7 @@ All available generators, across languages and inputs:
 | **Inputs** | [`payloads`](./payloads.md) | [`parameters`](./parameters.md) | [`headers`](./headers.md) | [`types`](./types.md) | [`channels`](./channels.md) | [`client`](./client.md) | [`custom`](./custom.md) |
 |---|---|---|---|---|---|---|---|
 | AsyncAPI | ✔️ | ✔️ | ✔️ | ✔️ | ✔️ | ✔️ | ✔️ |
+| OpenAPI | ➗ | ➗ | ➗ | ➗ | ➗ | ➗ | ✔️ |
 
 | **Languages** | [`payloads`](./payloads.md) | [`parameters`](./parameters.md) | [`headers`](./headers.md) | [`types`](./types.md) | [`channels`](./channels.md) | [`client`](./client.md) | [`custom`](./custom.md) |
 |---|---|---|---|---|---|---|---|

docs/generators/custom.md

@@ -18,7 +18,7 @@ export default {
     {
       preset: 'custom',
       ...
-      renderFunction: ({generator, inputType, asyncapiDocument, dependencyOutputs}) 
+      renderFunction: ({generator, inputType, asyncapiDocument, openapiDocument, dependencyOutputs}) 
       {
         const modelinaGenerator = new JavaFileGenerator({});
         modelinaGenerator.generateCompleteModels(...)
@@ -30,7 +30,7 @@ export default {
 
 # Dependencies
 
-In each generator (don't manually use it unless you use `preset: custom`, you can add `dependencies` property, which takes an array of `id`'s that the rendering engine ensures are rendered before the dependant one. 
+In each generator (don't manually use it unless you use `preset: custom`), you can add `dependencies` property, which takes an array of `id`'s that the rendering engine ensures are rendered before the dependant one. 
 
 Each generator has a specific output (except `custom` which is dynamic and under your control), they are documented under each [./generators](./README.md). These outputs can be accessed under `dependencyOutputs`.
 
@@ -70,4 +70,5 @@ In the `renderFunction` you have access to a bunch of arguments to help you crea
 - `generator` - is the generator configuration, where you have access to the `options` and all other information.
 - `inputType` - is the root `inputType` for the input document
 - `asyncapiDocument` - is the parsed AsyncAPI document input (according to the [AsyncAPI parser](https://github.com/asyncapi/parser-js/)), undefined if the `inputType` is not `asyncapi`
+- `openapiDocument` - is the parsed OpenAPI document input (according to the [readme/openapi-parser](https://github.com/readmeio/oas)), undefined if the `inputType` is not `openapi`
 - `dependencyOutputs` - if you have defined any `dependencies`, this is where you can access the output. Checkout the [dependency documentation](#dependencies) for more information.

docs/inputs/openapi.md

@@ -0,0 +1,140 @@
+---
+sidebar_position: 99
+---
+
+# OpenAPI
+
+Input support; `openapi`
+
+- OpenAPI 3.0.x
+- OpenAPI 3.1.x
+- Swagger 2.0 (legacy support)
+
+## Basic Usage
+
+### Configuration
+
+Create a configuration file that specifies OpenAPI as the input type:
+
+```json
+{
+  "inputType": "openapi",
+  "inputPath": "./api/openapi.yaml",
+  "language": "typescript",
+  "generators": [ ... ]
+}
+```
+
+## Supported Generators
+
+### Custom Generator
+
+For advanced use cases, you can create [custom generators](../generators/custom.md):
+
+```json
+{
+  "inputType": "openapi",
+  "inputPath": "./api/openapi.yaml",
+  "language": "typescript",
+  "generators": [
+    {
+      preset: 'custom',
+      ...
+      renderFunction: ({generator, inputType, openapiDocument, dependencyOutputs}) 
+      {
+        const modelinaGenerator = new JavaFileGenerator({});
+        modelinaGenerator.generateCompleteModels(...)
+      }
+    }
+  ]
+}
+
+```
+
+## Advanced Features
+
+### External References
+
+The OpenAPI parser automatically resolves external `$ref` references:
+
+```yaml
+components:
+  schemas:
+    Pet:
+      $ref: './schemas/pet.yaml#/Pet'
+    User:
+      $ref: 'https://api.example.com/schemas/user.json#/User'
+```
+
+### OpenAPI 3.1 Features
+
+Full support for OpenAPI 3.1 features including:
+
+- JSON Schema 2020-12 compatibility
+- `const` keyword
+- `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. 

docs/migrations/v0.md

@@ -60,3 +60,4 @@ const subscriber = await jetStreamPullSubscribeToReceiveUserSignedup({
 
 
 
+

docs/usage.md

@@ -9,7 +9,7 @@ $ npm install -g @the-codegen-project/cli
 $ codegen COMMAND
 running command...
 $ codegen (--version)
-@the-codegen-project/cli/0.41.0 linux-x64 node-v18.20.8
+@the-codegen-project/cli/0.41.0 win32-x64 node-v18.20.4
 $ codegen --help [COMMAND]
 USAGE
   $ codegen COMMAND
@@ -109,7 +109,7 @@ Initialize The Codegen Project in your project
 
 ```
 USAGE
-  $ codegen init [--help] [--input-file <value>] [--config-name <value>] [--input-type asyncapi]
+  $ codegen init [--help] [--input-file <value>] [--config-name <value>] [--input-type asyncapi|openapi]
     [--output-directory <value>] [--config-type esm|json|yaml|ts] [--languages typescript] [--no-tty]
     [--include-payloads] [--include-headers] [--include-client] [--include-parameters] [--include-channels]
 
@@ -128,7 +128,7 @@ FLAGS
   --include-payloads          Include payloads generation, available for TypeScript
   --input-file=<value>        File path for the code generation input such as AsyncAPI document
   --input-type=<option>       Input file type
-                              <options: asyncapi>
+                              <options: asyncapi|openapi>
   --languages=<option>        Which languages do you wish to generate code for?
                               <options: typescript>
   --no-tty                    Do not use an interactive terminal

package-lock.json

@@ -18,9 +18,11 @@
     "@oclif/plugin-autocomplete": "^3.0.16",
     "@oclif/plugin-help": "^6.0.21",
     "@oclif/plugin-version": "^2.0.17",
+    "@readme/openapi-parser": "^4.0.0",
     "cosmiconfig": "^9.0.0",
     "graphology": "^0.25.4",
     "inquirer": "^8.2.6",
+    "openapi-types": "^12.1.3",
     "yaml": "^2.4.5",
     "zod": "^3.23.8",
     "zod-validation-error": "^3.3.0"