Sign inSign up

cdcabrera/apidoc-mock

By cdcabrera

•Updated about 5 years ago

Apidoc mock server

Image
2

3.0K

cdcabrera/apidoc-mock repository overview

⁠Apidoc Mock

Build Status codecov 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⁠ @apiSucceessExample 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 apidock-mock

or Yarn

  $ yarn add apidock-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]
    -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 Docker setup

Apidoc Mock can also be found on Docker Hub...

⁠Example

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

  $ docker pull cdcabrera/apidoc-mock
  $ docker stop mock-api-test
  $ docker run -i --rm -p 8000:8000 --name mock-api-test cdcabrera/apidoc-mock

From there you should be able to navigate to

⁠Using within a project

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

      /**
   * @api {get} /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/
   * @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 Docker setup

    Make sure Docker is running, and pull in the Docker image. Setup something like...

      "scripts": {
    "mock:setup": "docker pull cdcabrera/apidoc-mock",
    "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 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/
   * @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/
   * @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/
   * @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/
   * @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⁠.

Tag summary

Content type

Image

Digest

Size

44.3 MB

Last updated

about 5 years ago

docker pull cdcabrera/apidoc-mock