swaggie 1.0.0 → 1.0.2-test.1

package/README.md

@@ -10,15 +10,27 @@
 ![npm downloads](https://img.shields.io/npm/dw/swaggie.svg)
 ![npm bundle size](https://img.shields.io/bundlephobia/minzip/swaggie.svg)
 ![npm install size](https://packagephobia.now.sh/badge?p=swaggie)
+![Hackage Dependencies](https://img.shields.io/hackage-deps/v/swaggie)
 
-<!-- ![Dependencies](https://img.shields.io/david/yhnavein/swaggie.svg) -->
-
-Generate ES6 or Typescript code from an OpenAPI 3.0 spec, so that accessing REST API resources from the client code is less error-prone, static-typed and just easier to use long-term.
+Generate Typescript code from an OpenAPI 3.0 document, so that accessing REST API resources from the client code is less error-prone, static-typed and just easier to use long-term.
 
 You can take a look at the [Examples section](#example) down below.
 
 Project is based and inspired by [OpenApi Client](https://github.com/mikestead/openapi-client).
 
+### Features
+
+- Generate TypeScript code from OpenAPI 3.0 spec
+- Supports `fetch`, `axios`, `xior`, `SWR + axios`, `Angular 1`, `Angular 2+` templates. It's flexible.
+- Possible to create your own template that works with your existing codebase
+- It's a dev tool that generates code, so it's not a runtime dependency
+- Support for `allOf`, `oneOf`, `anyOf` and `$ref` in schemas
+- Support for different types of enums
+- Support for different content types
+- JSDoc comments for generated code
+- Small library size and very small and tree-shakable output that is all placed in one file
+- OpenAPI 3.1 is partially supported (mostly enums, more to come)
+
 ## Install
 
 In your project
@@ -31,7 +43,7 @@ Or globally to run CLI from anywhere
 
 ## OpenAPI versions
 
-Swaggie from version 1.0 supports OpenAPI 3.0 (and some features of 3.1). Swagger or OpenAPI v2 documents are not supported anymore, but you have few options how to deal with it:
+Swaggie from version 1.0 supports OpenAPI 3.0 (and some features of 3.1). Swagger or OpenAPI 2.0 documents are not supported anymore, but you have few options how to deal with it:
 
 - **(preferred)** From your backend server generate OpenAPI 3.0 spec instead of version 2 (samples are updated to use OpenAPI 3.0)
 - Convert your OpenAPI 2.0 spec to 3.0 using [swagger2openapi](https://www.npmjs.com/package/swagger2openapi) tool (or something similar)
@@ -65,7 +77,7 @@ Options:
 Sample CLI usage using Swagger's Pet Store:
 
 ```bash
-swaggie -s https://petstore3.swagger.io/api/v3/openapi.json -o ./client/petstore/
+swaggie -s https://petstore3.swagger.io/api/v3/openapi.json -o ./client/petstore.ts
 ```
 
 `swaggie` outputs TypeScript that is somehow formatted, but it's far from perfect. You can adjust the generated code by prettifying output using your preferred beautify tool using your repo's styling guidelines. For example involving `prettier` looks like this:
@@ -104,17 +116,18 @@ Sample configuration looks like this:
 The following templates are bundled with Swaggie:
 
 ```
-axios     Default template. Recommended for React / Vue / similar frameworks. Uses axios
-xior      Lightweight and modern alternative to axios. Uses [xior](https://github.com/suhaotian/xior#intro)
-swr-axios Template that embraces SRW for GET requests and as a fallback uses axios.
-fetch     Template similar to axios, but with fetch API instead. Recommended for React / Vue / similar frameworks
-ng1       Template for Angular 1 (this is for the old one)
-ng2       Template for Angular 2+ (uses HttpClient, InjectionTokens, etc)
+axios          Default template. Recommended for React / Vue / similar frameworks. Uses axios
+xior           Lightweight and modern alternative to axios. Uses [xior](https://github.com/suhaotian/xior#intro)
+swr-axios      Template that embraces SRW for GET requests and as a fallback uses axios.
+tanstack-query Template that uses TanStack Query for GET requests and as a fallback uses xior.
+fetch          Template similar to axios, but with fetch API instead. Recommended for React / Vue / similar frameworks
+ng1            Template for Angular 1 (this is for the old one)
+ng2            Template for Angular 2+ (uses HttpClient, InjectionTokens, etc)
 ```
 
 If you want to use your own template, you can use the path to your template for the `-t` parameter:
 
-```
+```bash
 swaggie -s https://petstore3.swagger.io/api/v3/openapi.json -o ./client/petstore --template ./my-swaggie-template/
 ```
 
@@ -159,13 +172,13 @@ Once you know what your backend expects, you can adjust the configuration file a
 
 [prettier](https://prettier.io/) - the most popular one
 
-```sh
+```bash
 prettier ./FILE_PATH.ts --write
 ```
 
 [biome](https://biomejs.dev) - the super fast one
 
-```sh
+```bash
 biome check ./FILE_PATH.ts --apply-unsafe
 ```
 
@@ -235,44 +248,6 @@ You might wonder how to set up server to fully utilize Swaggie's features. For t
 
 Server is not necessary to use Swaggie. Swaggie cares only about the JSON/yaml file with the Open API spec, but for your development purpose you might want to have a server that can serve this file automatically from the actual endpoints.
 
-## Competitors
-
-If you are familiar with the client-code generators for the Swagger / OpenAPI standards then you might wonder why `swaggie` is better than existing tools. I compiled a quick comparison with other tools below:
-
-### Swaggie
-
-- Fast and small ![swaggie size](https://packagephobia.now.sh/badge?p=swaggie)
-- Lightweight and easy to start
-- Easy to contribute to, custom templates
-- Flexible, suits well in the existing apps
-- Generates REST clients and all models
-- Supports different templates (like `axios`, `fetch`, `xior`, `swr-axios`, `ng1`, `ng2`)
-- Written in TypeScript
-- Generates only one file with everything you need inside
-
-### [NSwag](https://github.com/RicoSuter/NSwag)
-
-- Slow and big ![nswag size](https://packagephobia.now.sh/badge?p=nswag)
-- Complicated templates, not easy to contribute to
-- Enforces usage of other tools and architecture
-- Generates more boilerplate code
-- Written in .NET, require .NET to execute, although published to npm as well
-- Many more features (but mostly for .NET apps), client generation is just a part of it
-
-### [Hey API](https://heyapi.vercel.app)
-
-- Fast and small ![nswag size](https://packagephobia.now.sh/badge?p=%40hey-api%2Fopenapi-ts)
-- No flexibility, other clients are discouraged from use
-- Generates a lot of code and multiple files
-- Written in TypeScript
-
-### [Kiota](https://learn.microsoft.com/en-us/openapi/kiota/)
-
-- A lot of boilerplate code and many files
-- Written in .NET, requires .NET to execute, published to NuGet
-- Not flexible at all - you need to use their architecture in your code
-- Looks like an enterprise solution with many configuration options
-
 ## Using Swaggie programmatically
 
 ```javascript
@@ -297,7 +272,7 @@ function error(e) {
 
 | Supported                                                                      | Not supported                              |
 | ------------------------------------------------------------------------------ | ------------------------------------------ |
-| OpenAPI 3                                                                      | Swagger 2                                  |
+| OpenAPI 3                                                                      | Swagger, Open API 2.0                      |
 | `allOf`, `oneOf`, `anyOf`, `$ref` to schemas                                   | `not`                                      |
 | Spec formats: `JSON`, `YAML`                                                   | Very complex query params                  |
 | Extensions: `x-position`, `x-name`, `x-enumNames`, `x-enum-varnames`           | Multiple response types (one will be used) |
@@ -307,3 +282,10 @@ function error(e) {
 | Paths inheritance, comments (descriptions)                                     |                                            |
 | Getting documents from remote locations or as path reference (local file)      |                                            |
 | Grouping endpoints by tags + handle gracefully duplicate operation ids         |                                            |
+
+## Used by
+
+<div style="display: flex; gap: 1rem;">
+<a href="https://www.britishcouncil.org"><img alt="British Council" src="https://upload.wikimedia.org/wikipedia/commons/thumb/e/e1/BritishCouncil.png/320px-BritishCouncil.png" style="height: 50px;" /></a>
+<a href="https://kpmg.com/"><img alt="KPMG" src="https://upload.wikimedia.org/wikipedia/commons/thumb/3/31/KPMG.svg/320px-KPMG.svg.png" style="height: 50px;" /></a>
+</div>

package/dist/types.d.ts

@@ -29,7 +29,7 @@ export interface FullAppOptions extends ClientOptions {
     /** Path to the configuration file that contains actual config to be used */
     config?: string;
 }
-export type Template = 'axios' | 'fetch' | 'ng1' | 'ng2' | 'swr-axios' | 'xior';
+export type Template = 'axios' | 'fetch' | 'ng1' | 'ng2' | 'swr-axios' | 'xior' | 'tanstack-query';
 export type HttpMethod = 'get' | 'put' | 'post' | 'delete' | 'options' | 'head' | 'patch';
 export type DateSupport = 'string' | 'Date';
 export type ArrayFormat = 'indices' | 'repeat' | 'brackets';

package/dist/utils/index.js

@@ -1,4 +1,3 @@
 "use strict";Object.defineProperty(exports, "__esModule", {value: true}); function _createStarExport(obj) { Object.keys(obj) .filter((key) => key !== "default" && key !== "__esModule") .forEach((key) => { if (exports.hasOwnProperty(key)) { return; } Object.defineProperty(exports, key, {enumerable: true, configurable: true, get: () => obj[key]}); }); }var _utils = require('./utils'); _createStarExport(_utils);
 var _documentLoader = require('./documentLoader'); _createStarExport(_documentLoader);
-var _testutils = require('./test.utils'); _createStarExport(_testutils);
 var _templateManager = require('./templateManager'); _createStarExport(_templateManager);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "swaggie",
-  "version": "1.0.0",
+  "version": "1.0.2-test.1",
   "description": "Generate TypeScript REST client code from an OpenAPI spec",
   "author": {
     "name": "Piotr Dabrowski",
@@ -25,7 +25,7 @@
   },
   "scripts": {
     "build": "sucrase ./src -d ./dist --transforms typescript,imports && npm run rm-tests && npm run types",
-    "rm-tests": "find dist/ -name '*.spec.js' -type f -delete",
+    "rm-tests": "find dist/ \\( -name '*.spec.js' -o -name 'types.js' \\) -type f -delete",
     "types": "tsc src/types.ts --outDir dist/ --declaration --emitDeclarationOnly && cp test/index.d.ts ./dist/",
     "test": "mocha",
     "coverage": "npx nyc -r text -r json-summary mocha"
@@ -51,21 +51,21 @@
   ],
   "dependencies": {
     "case": "^1.6.3",
-    "commander": "^12.1.0",
-    "eta": "^3.4.0",
+    "commander": "^13.1.0",
+    "eta": "^3.5.0",
     "js-yaml": "^4.1.0",
     "nanocolors": "^0.2.0",
-    "undici": "^6.19.2"
+    "undici": "^7.3.0"
   },
   "devDependencies": {
-    "@types/chai": "4.3.16",
+    "@types/chai": "5.0.1",
     "@types/js-yaml": "4.0.9",
-    "@types/mocha": "10.0.7",
-    "@types/node": "20.14.9",
-    "chai": "4.4.1",
-    "mocha": "10.6.0",
+    "@types/mocha": "10.0.10",
+    "@types/node": "22.13.1",
+    "chai": "5.1.2",
+    "mocha": "11.1.0",
     "openapi-types": "^12.1.3",
     "sucrase": "3.35.0",
-    "typescript": "5.5.3"
+    "typescript": "5.7.3"
   }
 }

package/templates/tanstack-query/baseClient.ejs

@@ -0,0 +1,25 @@
+/* tslint:disable */
+/* eslint-disable */
+//----------------------
+// <auto-generated>
+//   Generated using Swaggie (https://github.com/yhnavein/swaggie)
+//   Please avoid doing any manual changes in this file
+// </auto-generated>
+//----------------------
+// ReSharper disable InconsistentNaming
+// deno-lint-ignore-file
+
+import xior, { type XiorResponse, type XiorRequestConfig, encodeParams } from "xior";
+import { QueryClient, type UndefinedInitialDataOptions, useQuery } from '@tanstack/react-query';
+
+export const queryClient = new QueryClient();
+
+export const http = xior.create({
+  baseURL: '<%= it.baseUrl || '' %>',
+  paramsSerializer: (params) =>
+    encodeParams(params, true, null, {
+      allowDots: <%= it.allowDots %>,
+      arrayFormat: '<%= it.arrayFormat %>',
+    }),
+});
+

package/templates/tanstack-query/client.ejs

@@ -0,0 +1,22 @@
+export const <%= it.camelCaseName %>Client = {
+  <% it.operations.forEach((operation) => { %>
+<%~ include('operation.ejs', operation); %>
+
+<% }); %>
+};
+
+
+<% var getOperations = it.operations.filter((o) => o.method === 'GET');
+if(getOperations.length > 0) { %>
+  <% getOperations.forEach((operation) => {
+  var opName = operation.name;
+  if(opName.toLowerCase().startsWith("get")) {
+    opName = opName.substring(3);
+  }
+  opName[0] = opName[0].toUpperCase();
+  var customName = "use" + it.clientName + opName;
+  var queryOperation = Object.assign({ rqOpName: customName, opKey: it.clientName + opName, clientName: it.camelCaseName }, operation); %>
+<%~ include('queryOperation.ejs', queryOperation); %>
+
+  <% }); %>
+<% } %>

package/templates/tanstack-query/operation.ejs

@@ -0,0 +1,44 @@
+  /**
+<% it.parameters.forEach((parameter) => { %>
+   * @param <%= parameter.name %> <%= parameter.optional ? '(optional)' : '' %> <%= parameter.name !== parameter.originalName ? `(API name: ${parameter.originalName})` : '' %>
+
+<% }); -%>
+   */
+  <%= it.name %>(<% it.parameters.forEach((parameter) => { %>
+<%= parameter.name %>: <%~ parameter.type %> <%= parameter.optional ? '| null | undefined' : '' %>,
+    <% }); %>
+$config?: XiorRequestConfig
+  ): Promise<XiorResponse<<%~ it.returnType %>>> {
+    const url = `<%= it.url %>`;
+
+    return http.request<<%~ it.returnType %>>({
+      url: url,
+      method: '<%= it.method %>',
+<% if(it.body) { %>
+<% if(it.body.contentType === 'urlencoded') { %>
+      data: new URLSearchParams(<%= it.body.name %> as any),
+<% } else { %>
+      data: <%= it.body.name %>,
+<% } %>
+<% } %>
+<% if(it.query && it.query.length > 0) { %>
+      params: {
+    <% it.query.forEach((parameter) => { %>
+    '<%= parameter.originalName %>': <%= parameter.name %>,
+    <% }); %>
+  },
+<% } %>
+<% if(it.headers && it.headers.length > 0) { %>
+      headers: {
+  <% it.headers.forEach((parameter) => { %>
+    <% if (parameter.value) { %>
+  '<%= parameter.originalName %>': '<%= parameter.value %>',
+    <% } else { %>
+  '<%= parameter.originalName %>': <%= parameter.name %>,
+    <% } %>
+  <% }); %>
+},
+<% } %>
+      ...$config,
+    });
+  },

package/templates/tanstack-query/queryOperation.ejs

@@ -0,0 +1,21 @@
+/**
+<% it.parameters.forEach((parameter) => { %>
+   * @param <%= parameter.name %> <%= parameter.optional ? '(optional)' : '' %> <%= parameter.name !== parameter.originalName ? `(API name: ${parameter.originalName})` : '' %>
+
+<% }); -%>
+   * @param $config (optional) Additional configuration for TanStack Query
+   * @param $httpConfig (optional) Additional configuration for xior request (actually executes the request)
+   */
+export function <%= it.rqOpName %>(<% it.parameters.forEach((parameter) => { %>
+  <%= parameter.name %>: <%~ parameter.type %> <%= parameter.optional ? ' | null | undefined' : '' %>,
+    <% }); %>
+$config?: UndefinedInitialDataOptions<<%~ it.returnType %>, Error, <%~ it.returnType %>>,
+    $httpConfig?: XiorRequestConfig
+  ) {
+  return useQuery({
+    queryKey: ['<%= it.clientName %>', '<%= it.opKey %>', <% it.query.forEach((parameter) => { %><%= parameter.name %>, <% }); %>],
+    queryFn: () => <%= it.clientName %>Client.<%= it.name %>(<% it.parameters.forEach((parameter) => { %>
+<%= parameter.name %>, <% }); %>$httpConfig),
+    ...$config
+  });
+}

package/dist/types.js

@@ -1,49 +0,0 @@
-"use strict";
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-

package/dist/utils/test.utils.js

@@ -1,64 +0,0 @@
-"use strict";Object.defineProperty(exports, "__esModule", {value: true}); function _interopRequireDefault(obj) { return obj && obj.__esModule ? obj : { default: obj }; }var _nodefs = require('node:fs'); var _nodefs2 = _interopRequireDefault(_nodefs);
-var _nodepath = require('node:path'); var _nodepath2 = _interopRequireDefault(_nodepath);
-
-
-
-
-
-/**
- * Returns a valid OpenAPI 3.0 document with the minimal required fields.
- * And it allows to easily override any of the fields.
- */
- function getDocument(document = {}) {
-  return {
-    openapi: '3.0.0',
-    paths: {},
-    info: {
-      title: 'Test',
-      version: '1.0.0',
-    },
-    components: {},
-
-    ...document,
-  };
-} exports.getDocument = getDocument;
-
-/**
- * Returns a valid ClientOptions object with the minimal required fields.
- * And it allows to easily override any of the fields.
- */
- function getClientOptions(opts = {}) {
-  return {
-    src: 'http://example.com/swagger.json',
-    out: 'output.ts',
-    template: 'xior',
-    queryParamsSerialization: {
-      allowDots: true,
-      arrayFormat: 'repeat',
-    },
-    ...opts,
-  };
-} exports.getClientOptions = getClientOptions;
-
-/**
- * Utility that will set up a mock response for a given URL
- * @param mockAgent Agent that will be used to intercept the request
- * @param url Full URL to intercept
- * @param responseFileName Filename that contains the response. It will be loaded from the test folder
- */
- function mockRequest(mockAgent, url, responseFileName) {
-  const urlObject = new URL(url);
-  const mockPool = mockAgent.get(urlObject.origin);
-
-  const response = _nodefs2.default.readFileSync(_nodepath2.default.join(__dirname, '..', '..', 'test', responseFileName), {
-    encoding: 'utf-8',
-  });
-
-  // Set up the mock response
-  mockPool
-    .intercept({
-      path: urlObject.pathname,
-      method: 'GET',
-    })
-    .reply(200, response);
-} exports.mockRequest = mockRequest;