Express 中文文档

🚂 generator-express-no-stress


Create awesome Express.js applications with best of breed tech including ES.next via Babel.js, structured logging with Pino, API validation and interactive documentation using an OpenAPI 3 or Swagger 2 spec, environment based config with dotenv, and linting with ESLint.

generator-express-no-stress 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 request and response validation, structured logging, environment driven config, and more. Simply run the generator and smile :-D

Here's what you get!

Install


Requires Node 8 or greater

  1. ``` shell
  2. npm install -g yo generator-express-no-stress
  3. ```

See here for use with Yarn and/or Docker
See here for Node 6 support

Scaffold


  1. ``` shell
  2. yo express-no-stress myapp
  3. cd myapp
  4. ```

Run


Run in development mode:

  1. ``` shell
  2. npm run dev
  3. ```

Package and run in production mode

  1. ``` shell
  2. npm run compile
  3. npm start
  4. ```

Test


  1. ``` shell
  2. npm test
  3. ```

Debug


Run one of the following, then attach your favorite inspector e.g. VSCode :

  1. ``` shell
  2. # debug the server
  3. npm run dev:debug

  5. # debug the tests
  6. npm run test:debug
  7. ```

Try it!


Interactive API doc at http://localhost:3000/api-explorer
Landing page at http://localhost:3000

Usage: CLI


  1. ``` shell
  2. yo express-no-stress [appname] [--yarn] [--docker]
  3. ```

Option default Description
:--- :--- :---
appname myapp The application folder
--yarn - Use the yarn package manager, instead of npm
--docker Install Docker 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 lint View a listing of all errors discovered by the linter
npm run lint:fix Fix all errors discovered by the linter
npm run compile Transpile source code for production use
npm start Run the in production mode. *Requires running npm run compile first

Debug in VSCode


Add these contents to your .vscode/launch.json file

Debug in WebStorm


Start debug in developmentmode via npm run dev:debug
From the "Run" menu, select "Debug"
Select "Edit Configurations..."
From the list of Templates on the left side of the dialog, select "Attach to Node.js/Chrome"
Press the "Debug" button to attach the WebStorm debugger

Deploy to the Cloud


e.g. CloudFoundry

  1. ``` sh
  2. cf push myapp

  4. ```

Use Yarn


  1. ``` sh
  2. # scaffold
  3. yo express-no-stress myapp --yarn
  4. cd myapp

  6. # run in development mode
  7. yarn run dev

  9. # run in production mode
  10. yarn run compile
  11. yarn start

  13. # test
  14. yarn test

  16. ```

What you get!


Express.js - Fast, unopinionated , minimalist web framework for Node.js

Babel.js - Use new syntax, right now without waiting for support

Pino - Extremely fast node.js logger, inspired by Bunyan. It also includes a shell utility to pretty-print its log files

dotenv - Loads environment variables from .env for nodejs projects

ESLint - a pluggable linting utility for JavaScript and JSX

Choose from the following ESLint lint rules:

Airbnb - A mostly reasonable approach to JavaScript
Prettier - Prettier is an opinionated code formatter

Swagger - is a simple yet powerful representation of your RESTful API

SwaggerUI - 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 request validation
API response validation (OpenAPI 3 only. Disabled by default)
To enable set OPENAPI_ENABLE_RESPONSE_VALIDATION=true in .env

Interactive API Doc


API Validation!


Oops! I the API caller forgot to pass a name field, no stress, we've got this!

Structured Logging


Structured logging out of the box!

raw


pretty


Structured logging pretty printed by default - great for dev!

API Validation Example


Simply describe your APIs with Swagger and automatically get:

API request validation
Interactive documentation

example


Swagger API spec


  1. ``` yaml
  2. swagger: '2.0'
  3. info:
  4.   version: 1.0.0
  5.   title: myapp
  6.   description: My cool app
  7. basePath: /api/v1
  8. tags:
  9.   - name: Examples
  10.     description: Simple example endpoints
  11.   - name: Specification
  12.     description: The swagger API specification

  14. consumes:
  15.   - application/json
  16. produces:
  17.   - application/json

  19. definitions:
  20.   ExampleBody:
  21.     type: object
  22.     title: example
  23.     required:
  24.       - name
  25.     properties:
  26.       name:
  27.         type: string
  28.         example: no_stress

  30. paths:
  31.   /examples:
  32.     get:
  33.       tags:
  34.         - Examples
  35.       description: Fetch all examples
  36.       responses:
  37.         200:
  38.           description: Returns all examples
  39.     post:
  40.       tags:
  41.         - Examples
  42.       description: Create a new example
  43.       parameters:
  44.         - name: example
  45.           in: body
  46.           description: an example
  47.           required: true
  48.           schema:
  49.             $ref: '#/definitions/ExampleBody'
  50.       responses:
  51.         200:
  52.           description: Returns all examples

  54.   /examples/{id}:
  55.     get:
  56.       tags:
  57.         - Examples
  58.       parameters:
  59.         - name: id
  60.           in: path
  61.           required: true
  62.           description: The id of the example to retrieve
  63.           type: integer
  64.       responses:
  65.         200:
  66.           description: Return the example with the specified id
  67.         404:
  68.           description: Example not found

  70.   /spec:
  71.     get:
  72.       tags:
  73.         - Specification
  74.       responses:
  75.         200:
  76.           description: Return the API specification
  77. ```

Invoke a POST request via the Interactive doc


Linting


express-no-stress uses ESLint and provides two choices, Airbnb or Prettier.

To add your own ESLint customizations, edit.eslintrc.json.

Note that the Airbnb variant provides a slightly modified Airbnb base configuration.

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:

server/routes.js - This references the implementation of all of your routes. Add as many routes as you like and point each route your express handler functions.
server/common/api.yaml - This file contains your OpenAPI spec. 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 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

Modify server/routes.js

  1. ``` js
  2.    // Change your original path e.g. /api/v1/examples, to:
  3.    app.use('/api/v2/examples', examplesRouter);
  4. ```

Modify server/common/api.yaml and update the api root:

  1. ``` yaml
  2.   # Change e.g. /api/v1 to /api/v2
  3.   servers:
  4.   - url: /api/v2  
  5. ```

License


MIT

Contributors ✨


Thanks goes to these wonderful people (emoji key ):

:--- :--- :--- :--- :--- :--- :--- :---

This project follows the all-contributors specification. Contributions of any kind welcome!