Skip to content

Files

Latest commit

 

History

History
150 lines (99 loc) · 6.93 KB

03-cli.md

File metadata and controls

150 lines (99 loc) · 6.93 KB

Prism CLI

Prism CLI has two commands: mock and proxy.

Mock Server

Mocking is available through the CLI mock command.

prism mock https://raw.githack.com/OAI/OpenAPI-Specification/master/examples/v3.0/petstore-expanded.yaml
✔  success   Prism is listening on http://127.0.0.1:4010
●  note      GET        http://127.0.0.1:4010/pets
●  note      POST       http://127.0.0.1:4010/pets
●  note      GET        http://127.0.0.1:4010/pets/10
●  note      DELETE     http://127.0.0.1:4010/pets/10

Here you can see all the "operations" (a.k.a endpoints or resources) that Prism has found in your API description. Prism will shove an example, default, or other reasonably realistic value in there so you can copy and paste (or Ctrl+Click / CMD+Click in fancy terminals) to open the URL in your browser.

You can use whatever HTTP client you like, for example, trusty curl:

curl -s -D "/dev/stderr" http://127.0.0.1:4010/pets/123 | json_pp

HTTP/1.1 200 OK
content-type: application/json
content-length: 85
Date: Thu, 09 May 2019 15:25:40 GMT
Connection: keep-alive

{
   "tag" : "proident et ",
   "id" : -66955049,
   "name" : "ut consectetur cillum sit exercitation"
}

Responses will be mocked using realistic data that conforms to the type in the description.

Auto-reloading

Prism watches for changes made to a document it was loaded with. When they happen, Prism restarts its HTTP server to reflect changes to operations. There is no need to manually stop and start a Prism server after a change to a specification file.

In case of removing all of the operations in a document, Prism will not be reloaded. In such a case, Prism will keep serving operations loaded with the previous restart.

Modifying Responses

Prism's behavior in looking for the response for your request can be modified with a series of parameters that you can either pass through the Prefer header or through a query string parameter. Query string parameters are deprecated and will be removed in the next major release.

Keep in mind, all the query parameters need to be prefixed with __ — so if the Prefer header parameter is code, the query string will be __code

Force Response Status

Prism can be forced to return different HTTP responses by specifying the status code in the Prefer header

curl -v http://127.0.0.1:4010/pets/123 -H "Prefer: code=404"

HTTP/1.1 404 Not Found
content-type: application/json
content-length: 52
Date: Thu, 09 May 2019 15:26:07 GMT
Connection: keep-alive

The body, headers, etc. for this response will be taken from the API description document.

Request Specific Examples

You can request a specific example from your document by using the Prefer header example

curl -v http://127.0.0.1:4010/pets/123 -H "Prefer: example=exampleKey"

Dynamic Response

You can override the --dynamic|-d CLI param (which decides whether the generated example is static or dynamic) through the dynamic key in the Prefer header.

curl -v http://127.0.0.1:4010/pets/123 -H "Prefer: dynamic=false"

Remember: you can combine code, example and dynamic parameters. By default, when the code parameter is not given, Prism will always try to fetch an example using the exampleKey from the 200 HTTP responses only. You'll need to use the code parameter alongside the example one for any specific example using a different HTTP status code than 200.

Circular references

Even though Prism is technically able to internally handle circular references, the CLI will refuse to mock the provided document in case any circular reference is detected. This is essentially because serialising a circular reference is difficult and very dependant on the content type.

Proxy

This command creates an HTTP server that will proxy all the requests to the specified upstream server. Prism will analyze the request coming in and the response coming back from the upstream server and report the discrepancies with what's declared in the provided OpenAPI document.

Learn more about the ideas here in our Validation Proxy guide, or see below for the quick n dirty how to CLI.

$ prism proxy examples/petstore.oas2.yaml https://petstore.swagger.io/v2

[CLI] ...  awaiting  Starting Prism...
[HTTP SERVER] ℹ  info      Server listening at http://127.0.0.1:4010
[CLI] ●  note      GET        http://127.0.0.1:4010/pets
[CLI] ●  note      POST       http://127.0.0.1:4010/pets
[CLI] ●  note      GET        http://127.0.0.1:4010/pets/10

The output violations will be reported on the standard output and as a response header (sl-violations).

prism proxy examples/petstore.oas2.yaml https://petstore.swagger.io/v2
curl -v -s http://localhost:4010/pet/10 > /dev/null

< sl-violations: [{"location":["request"],"severity":"Error","code":401,"message":"Invalid security scheme used"}]

You can see there's a sl-violations header which is a JSON object with all the violations found in the response.

The header is a handy way to see contract mismatches or incorrect usage in a way that doesn't block the client, so you can monitor all/some production traffic this way record the problems. If you want Prism to make violations considerably more clear, run the proxy command with the --errors flag. This will turn any request or response violation into a RFC 7807 HTTP Problem Details Error just like validation errors on the mock server.

prism proxy examples/petstore.oas2.yaml https://petstore.swagger.io/v2 --errors
curl -v -X POST http://localhost:4010/pet/

< HTTP/1.1 422 Unprocessable Entity
{"type":"https://stoplight.io/prism/errors#UNPROCESSABLE_ENTITY","title":"Invalid request","status":422,"detail":"Your request/response is not valid and the --errors flag is set, so Prism is generating this error for you.","validation":[{"location":["request"],"severity":"Error","code":401,"message":"Invalid security scheme used"}]}

The response body contains the found output violations.

Server definitions (OAS3) and Host + BasePath (OAS2) are ignored. You need to manually specify the upstream URL when invoking Prism.

Running in Production

When running in development mode (which happens when the NODE_ENV environment variable is not set to production) or the -m flag is set to false, both the HTTP Server and the CLI (which is responsible of parsing and showing the received logs on the screen) will run within the same process.

Processing logs slows down Prism significantly. If you're planning to use the CLI in production (for example in a Docker Container) we recommend to run the CLI with the -m flag or set the NODE_ENV variable to production. In this way, the CLI and the HTTP server will run on two different processes, so that logs processing, parsing and printing does not slow down the http requests processing.