npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

@tiemma/sonic-express

v1.0.8

Published

Accelerate your swagger doc experience on an express backend

Downloads

302

Readme

sonic < express >

image

Accelerate your swagger doc experience on Express.

CodeQL Node.js CI

What does this do?

This hooks into the Express res and req API and auto-documents each response for you so you never have to.

Imagine writing 100 APIs and having it entirely documented, that's what this helps you with.

How to use it

  • Install the package
  • Import the middleware
  • Pass in the options
  • Sit back and call your APIs

Install the package

To install the package, run

npm install --save @tiemma/sonic-express

Import the middleware

The middleware for this project is currently exposed for only Express.

import { getResponseExpress } from '@tiemma/sonic-express';

Pass in the options

The express middleware requires three parameters

  • Top-level app instance
  • Swagger options (you can use the example here if you need one)
  • Path to where the generated swagger file should be saved
import { getResponseExpress } from '@tiemma/sonic-express';
import options from './swagger-config';

app.use(getResponseExpress(app, options, './examples/swagger.json'));

If you're considering adding this for other JS web frameworks, have a look at the core API here and see how to extract the required parameters for that framework.

Sit back and call your APIs

Once the middleware is initiated, all API calls that match the domains within servers[*].url in the swagger specification will be logged. For example, the servers block in the options stated here has an url entry for /api/v1. So all URLs containing /api/v1 will be logged, /api/v2 entries will not.

To enable for other URL prefixes, add the entry to the servers block and they will be automatically logged.

Why did I do this?

I got tired of tickets to update the swagger documentation which isn't easy or also extremely fun to do.

So whilst creating a simple handler to record the requests, I started this project.

What can I do with this?

You can use it to avoid writing a majority of the swagger specification or none at all for your express projects.

What specifications is this project written in?

Currently, the core API section starting here handles swagger 2 and 3 configurations quite fine.

Doubt it!?, test the swagger file here on editor.swagger.io. The spec listed above was generated using this same tool from tests here.

Best Practices

  1. Ensure you enable the middleware during tests
  • Unless you prefer overwriting parameters during development, it's best to keep the middleware working on a testing configuration so you don't mistakenly generate docs in production and slow down your API :-). The handler keeps the swaggerDoc in memory and writes updates per request.
if(process.env.NODE_ENV === 'testing') {
    app.use(getResponseExpress(app, options, './examples/swagger.json'));
}
  1. You can still add docs for your APIs
  • The middleware will adequately handle generating the swagger docs for undocumented routes. By undocumented routes, I mean routes without these fancy JSDoc comments
/**
 * @swagger
 * ...inserts more docs, arrrghhhh
 */

Despite the ease of this, be sure to add descriptions where needed for your end users.

/**
 * @swagger
 * /mouse/{id}/man:
 *   post:
 *     name: mouse
 *     summary: Create mouse
 *     description: Creates a mouse under a man's house, rhymes with the times dudes
 */
  1. That's about it from me, the rest is with you, me, the Issues page on this repo and Stackoverflow.

Debugging

Logs from the core API can be exposed by setting the DEBUG environment variable.

export DEBUG="@tiemma/sonic-core"

I found a bug, how can I contribute?

Open up a PR using the ISSUE TEMPLATE here