https://github.com/grandlinex/swagger-mate

https://github.com/grandlinex/swagger-mate

api grandlinex openapi openapi3 rest-api swagger swagger-ui typescript

Last synced: 2 months ago
JSON representation

• Host: GitHub
• URL: https://github.com/grandlinex/swagger-mate
• Owner: GrandlineX
• License: bsd-3-clause
• Created: 2023-06-19T11:21:42.000Z (about 3 years ago)
• Default Branch: master
• Last Pushed: 2026-01-18T03:22:24.000Z (5 months ago)
• Last Synced: 2026-01-18T07:09:29.805Z (5 months ago)
• Topics: api, grandlinex, openapi, openapi3, rest-api, swagger, swagger-ui, typescript
• Language: TypeScript
• Homepage: https://www.grandlinex.com/
• Size: 2.06 MB
• Stars: 1
• Watchers: 0
• Forks: 0
• Open Issues: 0
• Metadata Files:
  • Readme: README.md
  • License: LICENSE

Awesome Lists containing this project

README

          
# Swagger-Mate

> GrandLineX Swagger-Mate  project

[![GitHub](https://badge.fury.io/gh/grandlinex%2Fswagger-mate.svg)](https://github.com/GrandlineX/swagger-mate)

[![NPM](https://img.shields.io/static/v1?label=NPM&message=Package&color=red&logo=NPM)](https://www.npmjs.com/package/@grandlinex/swagger-mate)

![TS](https://img.shields.io/static/v1?label=Language&message=TypeScript&color=blue&logo=TypeScript)

### Status

![Quality Gate Status](https://sonarcloud.io/api/project_badges/measure?project=GrandlineX_swagger-mate&metric=alert_status)

![Security Rating](https://sonarcloud.io/api/project_badges/measure?project=GrandlineX_swagger-mate&metric=security_rating)

![Maintainability Rating](https://sonarcloud.io/api/project_badges/measure?project=GrandlineX_swagger-mate&metric=sqale_rating)

![Reliability Rating](https://sonarcloud.io/api/project_badges/measure?project=GrandlineX_swagger-mate&metric=reliability_rating)

![Coverage](https://sonarcloud.io/api/project_badges/measure?project=GrandlineX_swagger-mate&metric=coverage)

### Issues

![Bugs](https://sonarcloud.io/api/project_badges/measure?project=GrandlineX_swagger-mate&metric=bugs)

![Vulnerabilities](https://sonarcloud.io/api/project_badges/measure?project=GrandlineX_swagger-mate&metric=vulnerabilities)

![Code Smells](https://sonarcloud.io/api/project_badges/measure?project=GrandlineX_swagger-mate&metric=code_smells)

## Features

- Generate swagger.{json|yml} from code

- Generate Api client from swagger.{json|yml}

## Quick Start

### Install

1. Insatal npm package

```shell

  npm i  @grandlinex/swagger-mate

```

2. Update package.json 

```json

{

  //...

  "scripts": {

    "makeSpec": "swagger-mate",

    "serveSpec": "swagger-mate --serve",

    "buildSpecMain": "swagger-mate --build --main",

    "buildSpecDev": "swagger-mate --build --dev"

  },

  "glx": {

    "kernel": "dist/Kernel.js"

  }

  //...

}

```

|Command| Description                                                                       |

|---|-----------------------------------------------------------------------------------|

|`npm run makeSpec`| make `openapi.json`                                                               |

|`npm run serveSpec`| serve `openapi.json` with [swagger-ui](https://github.com/swagger-api/swagger-ui) |

|`npm run buildSpecMain`| build api client (prod)                                                           |

|`npm run buildSpecDev`| build api client (dev)                                                           |

### Serve option

> Default port = 9000

ENV variables

| ENV | Description              |

|-----|--------------------------|

|  SW_PORT   | set custom serve port    |

|  SW_AUTH   | set default bearer token |

## Define types

### Kernel

```typescript

import { SPathUtil, Swagger } from '@grandlinex/swagger-mate';

// OpenApi 3.0.3 - Root Api definition

@Swagger({

  info: {

    title: 'KernelTest',

    version: '0.1.0', // Version (optional) will be read from package.json

  },

  openapi: '3.0.3',

  servers: [

    {

      url: 'http://localhost:9257',

      description: 'LocalDev',

    },

  ],

  paths: {

      // Static definition

    '/version': {

      get: {

        description: 'Get version',

        operationId: 'getVersion',

        responses: SPathUtil.defaultResponse('200', '500'),

      },

    },

   // Dynamic definition will be read from @SPath

  },

  security: [

    {

      bearerAuth: [],

    },

  ],

  components: {

    securitySchemes: {

      bearerAuth: {

        type: 'http',

        scheme: 'bearer',

        bearerFormat: 'JWT',

      },

    },

  },

})

export default class SomeKernel {}

```

### Action

```typescript

import { SPathUtil, Swagger } from '@grandlinex/swagger-mate';

// OpenApi 3.0.3 - Patch definition

@SPath({

    '/test': {

        get: {

            description: 'test',

            operationId: 'getTest', // name for the js api client

            summary: 'Descritption summary',

            responses: SPathUtil.defaultResponse('200','400', '500')

        },

    },

})

export default class SomeBaseApiAction {}

```