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

swagger-inline

v7.0.1

Published

Generate an OpenAPI/Swagger definition from inline comments.

Downloads

56,503

Readme

Warning This library is no longer being actively maintained (except for critical security fixes) nor is it recommended. We recommend using JSON Schema-based, strongly-typed tools to generate your OpenAPI definition (e.g., FastAPI, fastify-swagger).

swagger-inline

Generate an OpenAPI/Swagger definition from inline comments.

npm Build

Installation

npm install swagger-inline --save-dev

Usage

CLI

npx swagger-inline [--base] [--format] <inputGlobs ...>

Example

npx swagger-inline "./*.js" --base 'swaggerBase.json' > api.json

Options

The inputGlobs argument is a list of files, or globs, to search for Swagger/OAS comments.

  • base: Base API specification to extend. Required
  • format: Output filetype: .json or .yaml (default: .json)
  • scope: Matches the scope field defined in each API. For example, if --scope public is supplied, all operations will be generated, if --scope private, only those operations that have a scope: private declaration will be included.

Library

swaggerInline([inputGlobs...], options) => Promise => json | yaml

Example

const swaggerInline = require('swagger-inline');

swaggerInline(['src/**/*.js', 'test/**/*.js'], {
  base: 'swaggerBase.json',
}).then(generatedSwagger => {
  /* ... */
});

Available options

  • base: Base specification to extend. Required
  • format: Output filetype: .json or .yaml (default: .json)
  • ignore: An array of globs for files to ignore. (default: ['node_modules/**/*', 'bower_modules/**/*'],
  • logger: Function called for logging. (default: empty closure)
  • metadata: Add additional annotations to the Swagger file, prefixed with x-si.
  • scope: Matches the scope field defined in each API. For example, if --scope public is supplied, all operations will be generated, if --scope private, only those operations that have a scope: private declaration will be included.
  • ignoreErrors: Ignore errors due to image files or unknown file types when parsing files. (default: false)

Examples

Standard usage

1) Create a project

swaggerBase.yaml

swagger: '2.0'
host: 'petstore.swagger.io'
basePath: '/api'
schemes: ['http']

api.js

/**
 * @api [get] /pets
 * bodyContentType: "application/json"
 * description: "Returns all pets from the system that the user has access to"
 * responses:
 *   "200":
 *     description: "A list of pets."
 *     schema:
 *       type: "String"
 */

api.route('/pets', function () {
  /* Pet code 😺 */
});

/**
 * @schema Pet
 * required:
 *   - id
 *   - name
 * properties:
 *   id:
 *     type: integer
 *     format: int64
 *   name:
 *     type: string
 *   tag:
 *     type: string
 */

// some schema related function

2) Run Command

swagger-inline './*.js' --base './swaggerBase.yaml'

Output:

swagger: '2.0'
host: petstore.swagger.io
basePath: /api
schemes:
  - http
paths:
  /pets:
    get:
      description: Returns all pets from the system that the user has access to
      responses:
        '200':
          description: A list of pets.
          schema:
            type: String
components:
  schemas:
    Pet:
      required:
        - id
        - name
      properties:
        id:
          type: integer
          format: int64
        name:
          type: string
        tag:
          type: string

Scoped compilations

With the --scope parameter, you can compile your files based on a specific target that you define within your inline comments. For example, we have an API with a GET /pets and POST /pets but only the GET operation is public. We can add scope: public to our GET operation documentation to tell swagger-inline what scope it's set under.

/**
 * @api [get] /pets
 * scope: public
 * description: "Returns all pets from the system that the user has access to"
 * responses:
 *   "200":
 *     description: "A list of pets."
 *     schema:
 *       type: "String"
 */

/**
 * @api [post] /pets
 * description: "Creates a new pet
 * responses:
 *   "200":
 *     description: "The created pet."
 */

Now when you run swagger-inline, you can supply --scope public and only the GET /pets operation will be picked up. Omit --scope public and everything will be picked up.

Parameter shorthand declarations

Defining a parameter in OpenAPI can be verbose, so you can define parameters via shorthands. If you require something more complex, you can use the full OpenAPI parameter syntax.

Here's a simple example:

(query) limit=5* {Integer:int32} Amount returned

It has a lot of info packed into a short space:

  • The parameter type: query
  • The name of the parameter: limit
  • The default value: 5
  • A flag to indicate that the parameter is required: *
  • The type: Integer
  • The format of the type: int32
  • The parameter description: Amount returned

Almost all of these are optional — you can write something as concise as this:

(query) limit