Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/cdimascio/generator-express-no-stress-typescript
π A Yeoman generator for Express.js based 12-factor apps and apis using Typescript
https://github.com/cdimascio/generator-express-no-stress-typescript
12-factor expressjs openapi openapi3 swagger typescript yeoman-generator
Last synced: 30 days ago
JSON representation
π A Yeoman generator for Express.js based 12-factor apps and apis using Typescript
- Host: GitHub
- URL: https://github.com/cdimascio/generator-express-no-stress-typescript
- Owner: cdimascio
- License: mit
- Created: 2017-05-29T22:33:47.000Z (over 7 years ago)
- Default Branch: master
- Last Pushed: 2023-07-12T15:22:04.000Z (over 1 year ago)
- Last Synced: 2024-09-30T15:01:22.654Z (about 1 month ago)
- Topics: 12-factor, expressjs, openapi, openapi3, swagger, typescript, yeoman-generator
- Language: TypeScript
- Homepage:
- Size: 7.11 MB
- Stars: 361
- Watchers: 10
- Forks: 43
- Open Issues: 7
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGE_HISTORY.md
- Funding: .github/FUNDING.yml
- License: LICENSE
Awesome Lists containing this project
README
# generator-express-no-stress-typescript
![](https://img.shields.io/badge/status-stable-green.svg) ![](https://img.shields.io/npm/v/generator-express-no-stress-typescript.svg) [![Codacy Badge](https://api.codacy.com/project/badge/Grade/21e362094c5a4c0da4841fc172cee95d)](https://www.codacy.com/app/cdimascio/generator-express-no-stress-typescript?utm_source=github.com&utm_medium=referral&utm_content=cdimascio/generator-express-no-stress-typescript&utm_campaign=Badge_Grade) [![](https://img.shields.io/gitter/room/cdimascio-oss/community?color=%23eb205a)](https://gitter.im/cdimascio-oss/community)
[![All Contributors](https://img.shields.io/badge/all_contributors-10-orange.svg?style=flat-square)](#contributors-)
![](https://img.shields.io/badge/license-MIT-blue.svg)
Create awesome [Express.js](http://www.expressjs.com) applications with best of breed tech including [Typescript](https://www.typescriptlang.org/), structured logging with [Pino](https://github.com/pinojs/pino), API validation and interactive documentation via an [OpenAPI 3](https://swagger.io/specification/) or [Swagger 2](https://swagger.io/specification/v2/) spec, environment based config with [dotenv](https://github.com/motdotla/dotenv).
generator-express-no-stress-typescript gets you up and running in seconds. It's ridiculously easy to configure. Heck, just take the defaults. Start it. Write code.
This generator scaffolds a fully functioning REST API server complete with interactive documentation, API validation, structured logging, environment driven config, and more. Simply run the generator and smile :-D
This project is a Typescript variant of [generator-express-no-stress](https://github.com/cdimascio/generator-express-no-stress)
[Here's what you get!](#what-you-get)
## Install
_Requires Node 6 or greater_
```shell
npm install -g yo generator-express-no-stress-typescript
```- See [here](#usage-cli) for use with Yarn and/or Docker
## Scaffold
```shell
yo express-no-stress-typescript myapp
cd myapp
```## Run
Run in _development mode_:
```shell
npm run dev
```Package and run in _production mode_
```shell
npm run compile
npm start
```## Test
```shell
npm test
```## Debug
Run one of the following, then attach your favorite inspector.
```shell
# debug the server
npm run dev:debug# debug the tests
npm run test:debug
```## Try it!
- Interactive API doc at [http://localhost:3000/api-explorer](http://localhost:3000/api-explorer)
- Landing page at [http://localhost:3000](http://localhost:3000)---
## Usage: CLI
```shell
yo express-no-stress-typescript [appname] [--yarn] [--docker]
```| Option | default | Description |
| ---------- | ------- | -------------------------------------------------------------------------- |
| `appname` | myapp | The application folder |
| `--yarn` | - | Use the [`yarn`](https://yarnpkg.com) package manager, instead of `npm` |
| `--docker` | | Install [Docker](https://www.docker.com/) artifacts including a Dockerfile |## Usage: Project
The sections below describe all usage options available once the project is generated/scaffolded.
### npm targets
| Target | Description |
| -------------------- | ------------------------------------------------------------------------ |
| `npm run dev` | Run in _development_ mode |
| `npm run dev:debug` | Debug in _development_ mode |
| `npm run test` | Run tests |
| `npm run test:debug` | Debug tests |
| `npm run compile` | Transpile source code for production use |
| `npm start` | Run the in _production_ mode. \*Requires running `npm run compile` first |### Deploy to the Cloud
e.g. CloudFoundry
```
cf push myapp
```### Use Yarn
```
# scaffold
yo express-no-stress-typescript myapp --yarn# start
cd myapp
npm start
```---
## What you get!
- [Typescript](https://www.typescriptlang.org/) - Typescript is a typed superset of JavaScript that compiles to plain JavaScript
- [Express.js](https://www.expressjs.com) - Fast, unopinionated
, minimalist web framework for Node.js
- [Pino](https://github.com/pinojs/pino) - Extremely fast node.js logger, inspired by Bunyan. It also includes a shell utility to pretty-print its log files
- [dotenv](https://github.com/motdotla/dotenv) - Loads environment variables from .env for nodejs projects
- [Swagger](http://swagger.io/) - is a simple yet powerful representation of your RESTful API.
- [SwaggerUI](http://swagger.io/) - dynamically generate beautiful documentation and sandbox from a Swagger-compliant API### API Validation
Simply describe your APIs with Swagger and automagically get for free:
- Interactive documentation
- API validation#### Interactive API Doc
![](https://github.com/cdimascio/generator-express-no-stress-typescript/raw/master/assets/interactive-doc1.png)
#### API Validation!
Oops! I the API caller forgot to pass a `name` field, no stress, we've got this!
![](https://github.com/cdimascio/generator-express-no-stress-typescript/raw/master/assets/api-validation.png)
### Structured Logging
Structured logging out of the box!
#### raw
![](https://github.com/cdimascio/generator-express-no-stress-typescript/raw/master/assets/logging-raw.png)
#### pretty
Structured logging pretty printed by default - great for dev!
![](https://github.com/cdimascio/generator-express-no-stress-typescript/raw/master/assets/logging-pretty.png)
### API Validation Example
Simply describe your APIs with Swagger and automatically get:
- API request validation
- Interactive documentation### example
#### Swagger API spec
```yaml
swagger: '2.0'
info:
version: 1.0.0
title: myapp
description: My cool app
basePath: /api/v1
tags:
- name: Examples
description: Simple example endpoints
- name: Specification
description: The swagger API specificationconsumes:
- application/json
produces:
- application/jsondefinitions:
ExampleBody:
type: object
title: example
required:
- name
properties:
name:
type: string
example: no_stresspaths:
/examples:
get:
tags:
- Examples
description: Fetch all examples
responses:
200:
description: Returns all examples
post:
tags:
- Examples
description: Create a new example
parameters:
- name: example
in: body
description: an example
required: true
schema:
$ref: '#/definitions/ExampleBody'
responses:
200:
description: Returns all examples/examples/{id}:
get:
tags:
- Examples
parameters:
- name: id
in: path
required: true
description: The id of the example to retrieve
type: integer
responses:
200:
description: Return the example with the specified id
404:
description: Example not found/spec:
get:
tags:
- Specification
responses:
200:
description: Return the API specification
```#### Invoke a POST request via the Interactive doc
![](https://github.com/cdimascio/generator-express-no-stress-typescript/raw/master/assets/interactive-doc.png)
## FAQ
**Q**: How do I modify the example API and make it my own?**A**: There are two key files that enable you to customize and describe your API:
1. `server/routes.ts` - This references the implementation of all of your routes. Add as many routes as you like and point each route your express handler functions.
2. `server/common/api.yaml` - This file contains your [OpenAPI spec](https://swagger.io/specification/). Describe your API here. It's recommended that you to declare any and all validation logic in this YAML. `express-no-stress-typescript` uses [express-openapi-validator](https://github.com/cdimascio/express-openapi-validator) to automatically handle all API validation based on what you've defined in the spec.**Q**: I previously generated an app, but I want to change the API root. How do I do this?
**A**: You need to make to small changes
1. Modify `server/routes.ts`
```javascript
// Change your original path e.g. /api/v1/examples, to:
app.use('/api/v2/examples', examplesRouter);
```2. Modify `server/common/api.yaml` and update the api root:
```yaml
# Change e.g. /api/v1 to /api/v2
servers:
- url: /api/v2
```## License
[MIT](LICENSE)
## Contributors β¨
Thanks goes to these wonderful people ([emoji key](https://allcontributors.org/docs/en/emoji-key)):
Harris BrakmiΔ
π»
Daniel Meyer
π
Viraj Trivedi
π»
Sangbeom Han
π
Stef de Goey
π»
Roger
π»
Vikash Chauhan
π» π
Tse Kit Yam
π π»
Randy Kamradt
π»
Vitthal Patil
π»
This project follows the [all-contributors](https://github.com/all-contributors/all-contributors) specification. Contributions of any kind welcome!