Naughty Platypus Memorabilia

    apidoc-mock

    4.1.0 • Public • Published

    Apidoc Mock

    Build Status codecov Docker Repository on Quay License

    Tired of overthinking mock solutions, use apidoc styled comments on your local files to create a mock NodeJS server.

    You can serve up exactly what you need. Everything from a 200 status, to forcing a random custom status. You can even force a delay to see how your codebase will handle loading scenarios with a balls slow API response.

    Requirements

    The basic requirements:

    Use

    Generate a "happy path" mock server from apidoc @apiSuccessExample annotations. Once the server is setup correctly you should be able update your code comments/annotations and have the mock(s) update with a browser refresh.

    CLI

    NPM install...

      $ npm i apidoc-mock

    or Yarn

      $ yarn add apidoc-mock

    Usage

      $ mock --help
      Create a mock server from apiDoc comments.
      
      Usage: mock [options]
      
      Options:
        -d, --docs     Output directory used to compile apidocs   [default: "./.docs"]
        -p, --port     Set mock port                                   [default: 8000]
        -s, --silent   Silence apiDoc's output warnings, errors
                                                             [boolean] [default: true]
        -w, --watch    Watch single, or multiple directories
        -h, --help     Show help                                             [boolean]
        -v, --version  Show version number                                   [boolean]
    

    Example

    If you have a project, you could setup a NPM script to do the following

      $ mock -p 5000 -w src/yourDirectory -w src/anotherDirectory

    Then follow the guide for apidoc. From there run the NPM script, and open localhost:5000/[PATH TO API ENDPOINT].

    It's recommended you make sure to .gitignore the .docs directory that gets generated for apidocs.

    Or roll with a container setup

    Apidoc Mock can be found on Quay.io ...

    Example

    The base Quay image comes preloaded with a "hello/world" example, the basics

      $ docker stop mock-api-test
      $ docker run -d --rm -p 8000:8000 --name mock-api-test quay.io/cdcabrera/apidoc-mock && docker ps

    From there you should be able to navigate to

    Using within a project

    Using ApiDocs

    The v0.5X.X+ range of ApiDocs, now, requires the description with its updated template (i.e. @api {get} /hello/world/ [a description]) if you want the docs to display. If you don't use that aspect of this package you can continue to leave it out.

    1. Setup your API annotations first. @apiSuccessExample is the only apiDoc example currently implemented.

        /**
         * @api {get} /hello/world/ Get
         * @apiGroup Hello World
         * @apiSuccess {String} foo
         * @apiSuccess {String} bar
         * @apiSuccessExample {json} Success-Response:
         *     HTTP/1.1 200 OK
         *     {
         *       "foo": "hello",
         *       "bar": "world"
         *     }
         */
        const getExample = () => {};
        
        /**
         * @api {post} /hello/world/ Post
         * @apiGroup Hello World
         * @apiHeader {String} Authorization Authorization: Token AUTH_TOKEN
         * @apiSuccess {String} foo
         * @apiSuccess {String} bar
         * @apiSuccessExample {json} Success-Response:
         *     HTTP/1.1 200 OK
         *     {
         *       "foo": "hello",
         *       "bar": "world"
         *     }
         */
        const postExample = () => {};
    2. Next

      Using a NPM script setup

      Then, make sure to .gitignore the .docs directory that gets generated for apidocs.

      Then, setup your NPM scripts

        "scripts": {
          "mock": "mock -p 5000 -w [PATH TO YOUR JS FILES] -w [ANOTHER PATH TO YOUR JS FILES]"
        }

      And then run your script

        $ npm run mock

      Or if you're using a container setup

      Make sure Docker, or Podman, is running, and pull in the Quay.io image. Setup something like...

        "scripts": {
          "mock:run": "docker stop mock-api-test; docker run -i --rm -p [YOUR PORT]:8000 -v \"$(pwd)[PATH TO YOUR JS FILES]:/app/data\" --name mock-api-test quay.io/cdcabrera/apidoc-mock"
        }

      You'll need to pick a port like... -p 8000:8000 and a directory path to pull the apiDoc code comments/annotations from... -v \"$(pwd)/src:/app/data\".

      Then, run your scripts

        $ npm run mock:setup
        $ npm run mock:run
    3. Finally, navigate to

      • the docs, http://localhost:[YOUR PORT]/docs/
      • the api, http://localhost:[YOUR PORT]/[PATH TO API ENDPOINT]

    More examples, and custom responses

    Apidoc Mock adds in a few different custom flags to help you identify or demonstrate API responses

    • @apiMock {Random|RandomResponse} - pull a random response from either success or error examples
    • @apiMock {RandomSuccess} - pull a random success from success examples
    • @apiMock {RandomError} - pull a random error from error examples
    • @apiMock {ForceStatus} [HTTP STATUS] - force a specific http status
    • @apiMock {DelayResponse} [MILLISECONDS] - force (in milliseconds) a delayed response
    1. Get random responses from both success and error examples with the @apiMock {RandomResponse} annotation

        /**
         * @api {get} /hello/world/ Get
         * @apiGroup Hello World
         * @apiMock {RandomResponse}
         * @apiSuccess {String} foo
         * @apiSuccess {String} bar
         * @apiSuccessExample {json} Success-Response:
         *     HTTP/1.1 200 OK
         *     {
         *       "foo": "hello",
         *       "bar": "world"
         *     }
         * @apiSuccessExample {json} Success-Response:
         *     HTTP/1.1 200 OK
         *     {
         *       "lorem": "dolor",
         *       "ipsum": "est"
         *     }
         * @apiError {String} bad
         * @apiError {String} request
         * @apiErrorExample {json} Error-Response:
         *     HTTP/1.1 400 OK
         *     {
         *       "bad": "hello",
         *       "request": "world"
         *     }
         */
        const getExample = () => {};
    2. Get a random success response with the @apiMock {RandomSuccess} annotation. Or get a random error with the @apiMock {RandomError} annotation

        /**
         * @api {get} /hello/world/ Get
         * @apiGroup Hello World
         * @apiMock {RandomSuccess}
         * @apiSuccess {String} foo
         * @apiSuccess {String} bar
         * @apiSuccessExample {json} Success-Response:
         *     HTTP/1.1 200 OK
         *     {
         *       "foo": "hello",
         *       "bar": "world"
         *     }
         * @apiSuccessExample {json} Success-Response:
         *     HTTP/1.1 200 OK
         *     {
         *       "lorem": "dolor",
         *       "ipsum": "est"
         *     }
         * @apiError {String} bad
         * @apiError {String} request
         * @apiErrorExample {json} Error-Response:
         *     HTTP/1.1 400 OK
         *     {
         *       "bad": "hello",
         *       "request": "world"
         *     }
         */
        const getExample = () => {};
    3. Force a specific response status with the @apiMock {ForceStatus} [STATUS GOES HERE] annotation. If you use a status without a supporting example the response status is still forced, but with fallback content.

        /**
         * @api {get} /hello/world/ Get
         * @apiGroup Hello World
         * @apiMock {ForceStatus} 400
         * @apiSuccess {String} foo
         * @apiSuccess {String} bar
         * @apiSuccessExample {json} Success-Response:
         *     HTTP/1.1 200 OK
         *     {
         *       "foo": "hello",
         *       "bar": "world"
         *     }
         * @apiError {String} bad
         * @apiError {String} request
         * @apiErrorExample {json} Error-Response:
         *     HTTP/1.1 400 OK
         *     {
         *       "bad": "hello",
         *       "request": "world"
         *     }
         */
        const getExample = () => {};
    4. Delay a response status with the @apiMock {DelayResponse} [MILLISECONDS GO HERE] annotation.

        /**
         * @api {get} /hello/world/ Get
         * @apiGroup Hello World
         * @apiMock {DelayResponse} 3000
         * @apiSuccess {String} foo
         * @apiSuccess {String} bar
         * @apiSuccessExample {json} Success-Response:
         *     HTTP/1.1 200 OK
         *     {
         *       "foo": "hello",
         *       "bar": "world"
         *     }
         * @apiError {String} bad
         * @apiError {String} request
         * @apiErrorExample {json} Error-Response:
         *     HTTP/1.1 400 OK
         *     {
         *       "bad": "hello",
         *       "request": "world"
         *     }
         */
        const getExample = () => {};

    Contributing

    Contributing? Guidelines can be found here CONTRIBUTING.md.

    Install

    npm i apidoc-mock

    DownloadsWeekly Downloads

    105

    Version

    4.1.0

    License

    MIT

    Unpacked Size

    46.2 kB

    Total Files

    12

    Last publish

    Collaborators

    • cdcabrera