Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

How to route to a response example in spec #111

Closed
morgs32 opened this issue Dec 19, 2017 · 10 comments

Comments

Projects
None yet
4 participants
@morgs32
Copy link

commented Dec 19, 2017

Prism says it can "Act as a mock server, routing incoming requests to example responses, ...".

I'm unable to get this functionality from using the petstore spec (locally):


    "/pet/{petId}": {
      "get": {
        "tags": [
          "pet"
        ],
        "summary": "Find pet by ID",
        "description": "Returns a single pet",
        "operationId": "getPetById",
        "produces": [
          "application/xml",
          "application/json"
        ],
        "parameters": [
          {
            "name": "petId",
            "in": "path",
            "description": "ID of pet to return",
            "required": true,
            "type": "integer",
            "format": "int64"
          }
        ],
        "responses": {
          "200": {
            "description": "successful operation",
            "schema": {
              "$ref": "#/definitions/Pet"
            },
            "example": {
              "application/json": {
                "name": "Puma"
              }
            },
            "examples": {
              "1": {
                "application/json": {
                  "name": "Shiloh"
                }
              },
              "2": {
                "application/json": {
                  "name": "Puma",
                  "type": "Dog",
                  "color": "Black",
                  "gender": "Female",
                  "breed": "Mixed"
                }
              }
            }
          },

@morgs32

This comment has been minimized.

Copy link
Author

commented Dec 19, 2017

I put example and examples above, I can't get it to work with either.

@pytlesk4

This comment has been minimized.

Copy link
Member

commented Dec 19, 2017

@morgs32 can you paste the command that you are using here? Also, run 'prism version' and let me know what the output is.

Also, example isn't a valid key in the swagger specs, but examples is valid. You should change your examples too something like this:

"examples": {
	"application/json": {
		"name": "Shiloh"
	},
	"application/json-2": {
		"name": "Puma",
		"type": "Dog",
		"color": "Black",
		"gender": "Female",
		"breed": "Mixed"
	}
}

The way you have your examples defined the response body that is mocked back by prism will be:

{
    "application/json": {
        "name": "Shiloh"
    }
}

I assume you want to mock back just:

{
    "name": "Shiloh"
}
@morgs32

This comment has been minimized.

Copy link
Author

commented Dec 20, 2017

Interesting! With application/json-2 how would I access that example by url?

@morgs32

This comment has been minimized.

Copy link
Author

commented Dec 20, 2017

And is there away to check the example against its own api contract?

@pytlesk4

This comment has been minimized.

Copy link
Member

commented Dec 20, 2017

What version of prism are you using? If you are using 0.6.x then you can't control which example get's mocked back.

If you are using 2.0.0-beta.7, then you will need to create a prism instance, easiest way to do that is use our new stoplight platform. Here is an example of a prism instance that we set up, it is mocking back a todo api, and you can control the examples by adding a query string parameter __example=idofexample.

For example:

https://gmztkmj2nvqxg5dfoi5hi33en5zs43lpmnvwk4roobzgs43nfz4w23a.prism.stoplight.io/todos
https://gmztkmj2nvqxg5dfoi5hi33en5zs43lpmnvwk4roobzgs43nfz4w23a.prism.stoplight.io/todos?__example=empty

  • __example defaults to the request path, if the example doesn't exist, then it tries to use the content type as the example key, and if that doesn't exist prism will just try to pick the first one example it comes across.

Other Settings:

  • To control the status code to mock back by set query string parameter: __code=500, default is 2xx
  • If you have a json schema defined and no example defined, prism will dynamically generate a mocked response for you based on the json schema.
  • If you have both a schema, and example defined you can set query string parameter: __dynamic=true to force a dynamic response. Default is false.
  • To control the content type mocked back set query parameter: __contentType=application/xml, defaults to application/json
  • Dynamic mocking only works for json responses, so if you want to mock back xml responses, you have to set an example.

You can download prism 2.0.0-beta.7 here: https://github.com/stoplightio/prism/tree/2.x

And you can run a prism instance from the command line by using this command:

prism serve exportURLForInstance

For the Todo Instance above it would be:

prism serve -d https://exporter.stoplight.io/3351/master/todos.mocker.prism.yml

This starts a server on localhost:4010, you can change the port prism starts on with: -p 4011.

You can copy the prism instance json to a project in stoplight, and replace the spec that is being mocked back by changing the spec in the prism instance config. Just update the API that prism is pointing to.

@pytlesk4

This comment has been minimized.

Copy link
Member

commented Dec 20, 2017

I am currently traveling for the holidays, and about to board my flight. I will set up an example on how to do that in the prism project above. But if you are feeling brave, you need to add a after rule for validation to your prism instance configuration.

Here is a scenario that does validation

I just added validation to the todos prism instance, Prism will add a header Sl-Valid to the response. If validation passes it will equal to true, otherwise it will be the errors from validation.

Talk soon.

@morgs32

This comment has been minimized.

Copy link
Author

commented Dec 20, 2017

@pytlesk4 I appreciate the details above. I'll give the beta a shot!

@kliyes

This comment has been minimized.

Copy link

commented May 16, 2018

@pytlesk4 Thanks for the explanation, it really helps a lot.

@pytlesk4

This comment has been minimized.

Copy link
Member

commented May 16, 2018

@kliyes Added some new abilities to the mock server, you can read about them here:

https://medium.com/@marc.calder/creating-meaningful-api-mocks-without-re-writing-the-whole-api-bb4054525214

@endrec

This comment has been minimized.

Copy link

commented May 16, 2018

@pytlesk4 I tried to follow Marc's article, but it does not seem to work. :( When I get to the "secret sauce", that URL returns a 400.

@pytlesk4 pytlesk4 closed this Apr 11, 2019

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
You can’t perform that action at this time.