[Question] Which status code is picked for response about spring-cloud-contract-swagger

[SvenBayer]

I should add the default behaviour of the Swagger converter described on my blog. It sets default values for Swagger fields. Regarding responses, it uses the most top response, assuming this is the happy case (200, 201). It assumes that the other responses are error cases. Issue: #4
Regarding examples, there is this repo (or do you mean something else by examples section?):
https://github.com/SvenBayer/spring-cloud-contract-swagger-sample

[marcingrzejszczak]

Yeah I meant examples inside a Swagger definition

[SvenBayer]

Have a look at param_swagger.yml:
https://github.com/SvenBayer/spring-cloud-contract-swagger/blob/master/src/test/resources/swagger/param_swagger.yml

There you have example and x-example fields (properties) for variables of the definitions. However, the values are stuck to the definitions and will be used for both, request and response. If you paste the param_swagger.yml to editor.swagger.io, you can see for each request/response the example values.

I hope I understood you right this time? 👍

[marcingrzejszczak]

I hope I understood you right this time? 👍

Almost ;)

Contract test requires a scenario. Given this request you get that response. Swagger gives you a schema - these are all request fields, these all response fields, these all possible status codes. Without an example section where you show an example of usage you're basically creating a contract with all request fields and a random status. You're not really showing how to use your API right? Or am I missing sth?

[SvenBayer]

Yes, partly. You can create with the example and x-example fields already some half-meaningful values for your request and response. However, it will only show you how to use the API on a syntax level but not on a semantic level.

Also you are currently restricted to one use-case per method/endpoint and as you said, all values will be send.

You could create a proper example by adding an x-example property to the schema field which represents a body in the response and request. Then, you could create a use-case that also exists in reality.

I see two actions for improving this framework:

• We want to exclude optional values in requests: #6
• We want to have scenarios that exist in reality: #5

Is this what you mean by example? I think this will enable real examples, right?
It is probably very difficult to enable more use-cases than one per request.

[marcingrzejszczak]

Yes, partly. You can create with the example and x-example fields already some half-meaningful values for your request and response. However, it will only show you how to use the API on a syntax level but not on a semantic level.

Again, you're talking about example of a field. I'm talking about example of a pair of request->response. Example like:

given: request with JSON `{"a":"a","b":"b"}`
when: POST at /foo
then: status code 200
and: body with field `{"a":"a","b":"b"}`

I don't care what all the possible inputs on the request side are. I wonder if that's even possible with Swagger (that's why I don't know if Swagger is a good choice for contract testing).

I have an incubator project for RAML that does sth similar - https://github.com/spring-cloud-incubator/spring-cloud-contract-raml

My conclusions were that you need 1 RAML per interaction and you need to use the default, example values. So maybe that's very similar to what you're saying actually.

[SvenBayer]

Swagger is like a collection of RAML, so it contains several endpoints. It is pretty similar to RAML. In Swagger you can add everywhere any new fields with an x- prefix, similar to the default fields in RAML. Like x-imaginarifield

Yes, you are right, Swagger is not a good choice for contract testing. Using Groovy, JSON or Yaml would be a lot better for specifying your API. Swagger should be generated by the Microservice.

However, some big conservative companies stick to defining their API with Swagger instead of using proper contracts. Therefore, instead of defining the API in two separate documents, maintaining those two documents (Swagger + contract) and risking inconsistency, it is better to define them in one document. This way, we can take at least partly benefit of CDC. That's why I created this library.

Yes, it is like with RAML. But since Swagger is a schema, you can only define one scenario/interaction per defined endpoint. Defining more scenarios within one endpoint definition would be possible but too confusing. This is because your example is mixed with your schema definition.

Did I get you now? :)

[marcingrzejszczak]

However, some big conservative companies stick to defining their API with Swagger instead of using proper contracts. Therefore, instead of defining the API in two separate documents, maintaining those two documents (Swagger + contract) and risking inconsistency, it is better to define them in one document. This way, we can take at least partly benefit of CDC. That's why I created this library.

I see, so maybe it's worth writing about it? And actually suggest to go the other way round. Create contract definitions and generate swagger from it?

Yes, it is like with RAML. But since Swagger is a schema, you can only define one scenario/interaction per defined endpoint. Defining more scenarios within one endpoint definition would be possible but too confusing. This is because your example is mixed with your schema

Can you have multiple Swagger files instead of having everything in one?

[SvenBayer]

Thanks, I added a recommendation to the Readme.

You could have one Swagger file for each request, but I think the general practise is to define your API for a Microservice in one Swagger document. I think, if a company sticks to using Swagger for API specification they will stick to define all APIs for a Microservice in one Swagger file.

I already had some ideas of how to enable multiple scenarios, like enabling a x-401 etc parameter that you can add to enable a scenario for a 401 response. But this could be a bit confusing.
Another solution would be to write a Spring Cloud Contract Swagger Verifier that checks if your Groovy contract and Swagger file are compatible. Maybe this could enable projects to move from Swagger contract tests slowly to Groovy contract tests over time.

You can see at https://editor.swagger.io/ an example Swagger file and on the right. If you add example, x-example, default fields, they appear on the right too.

[marcingrzejszczak]

I don't know if that's useful but there's also this - https://bitbucket.org/atlassian/swagger-request-validator . We do generate a wiremock mappings so you can assert whether WireMock is compatible with given Swagger spec.

[SvenBayer]

Ah yes, this would be one's choice if you want to take advantage of Spring Cloud Contract and combine it with Swagger. Then you have two maintain two separate documents.

It looks like you could also use the swagger-request-validator for moving from Swagger "contracts" to proper Spring Cloud Contracts. Depending on how detailed you want to use CDC.

[SvenBayer]

Closing this question as it seems to be answered. @marcingrzejszczak thank you a lot for your ideas. Feel free to open any new questions!