{"id":16897402,"url":"https://github.com/robwin/assertj-swagger","last_synced_at":"2025-04-07T08:26:20.205Z","repository":{"id":31656104,"uuid":"35221452","full_name":"RobWin/assertj-swagger","owner":"RobWin","description":"A Swagger assertj test library which compares a contract-first Swagger YAML/JSON file with a code-first Swagger JSON","archived":false,"fork":false,"pushed_at":"2021-01-11T08:14:34.000Z","size":252,"stargazers_count":171,"open_issues_count":14,"forks_count":43,"subscribers_count":7,"default_branch":"master","last_synced_at":"2025-03-31T06:09:27.187Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/RobWin.png","metadata":{"files":{"readme":"README.adoc","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2015-05-07T13:25:14.000Z","updated_at":"2024-08-09T12:24:28.000Z","dependencies_parsed_at":"2022-09-26T22:10:52.878Z","dependency_job_id":null,"html_url":"https://github.com/RobWin/assertj-swagger","commit_stats":null,"previous_names":[],"tags_count":12,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/RobWin%2Fassertj-swagger","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/RobWin%2Fassertj-swagger/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/RobWin%2Fassertj-swagger/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/RobWin%2Fassertj-swagger/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/RobWin","download_url":"https://codeload.github.com/RobWin/assertj-swagger/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247617299,"owners_count":20967575,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-10-13T17:36:54.129Z","updated_at":"2025-04-07T08:26:20.176Z","avatar_url":"https://github.com/RobWin.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"= assertj-swagger\n:author: Robert Winkler\n:version: 0.9.0\n:hardbreaks:\n\nimage:https://travis-ci.org/RobWin/assertj-swagger.svg[\"Build Status\", link=\"https://travis-ci.org/RobWin/assertj-swagger\"] image:https://coveralls.io/repos/RobWin/assertj-swagger/badge.svg?branch=master[\"Coverage Status\", link=\"https://coveralls.io/r/RobWin/assertj-swagger\"] image:https://api.bintray.com/packages/robwin/maven/assertj-swagger/images/download.svg[link=\"https://bintray.com/robwin/maven/assertj-swagger/_latestVersion\"] image:http://img.shields.io/badge/license-ASF2-blue.svg[\"Apache License 2\", link=\"http://www.apache.org/licenses/LICENSE-2.0.txt\"] image:https://img.shields.io/badge/Twitter-rbrtwnklr-blue.svg[\"Twitter\", link=\"https://twitter.com/rbrtwnklr\"]\n\n== Overview\n\nassertj-swagger is a https://github.com/joel-costigliola/assertj-core[assertj] library which compares a contract-first https://github.com/swagger-api/swagger-spec[Swagger] YAML/JSON file with a code-first Swagger JSON output (e.g. from https://github.com/springfox/springfox[springfox] or https://github.com/swagger-api/swagger-core/wiki/Java-JAXRS-Quickstart[JAX-RS Swagger]). assertj-swagger allows to validate that the API implementation is in compliance with a contract specification for two test patterns: Documentation Driven Contracts and Consumer Driven Contracts.\n\nThe Documentation Driven Contracts test pattern, useful for public APIs, validates using `#isEqualTo` and will validate that the design first documentation contract matches the implementation in its entirety.\n\nThe Consumer Driven Contracts test pattern, useful for internal microservice APIs, validates using `#satisfiesContract` and will validate that the implementation provides, at minimum, the requirements of the design first consumer contract.  This pattern allows for extension points in the API resources, resource methods, and models.\n\nThe library supports the Swagger v2.0 specification. assertj-swagger compares Swagger objects like Paths, Parameters and Definitions. It does not compare __unimportant__ Swagger objects like info, descriptions or summaries.\n\n== Usage guide\n\n=== Adding assertj-swagger to your project\nThe project is published in JCenter and Maven Central.\n\n==== Maven\n\n[source,xml, subs=\"specialcharacters,attributes\"]\n----\n\u003crepositories\u003e\n    \u003crepository\u003e\n        \u003csnapshots\u003e\n            \u003cenabled\u003efalse\u003c/enabled\u003e\n        \u003c/snapshots\u003e\n        \u003cid\u003ecentral\u003c/id\u003e\n        \u003cname\u003ebintray\u003c/name\u003e\n        \u003curl\u003ehttp://jcenter.bintray.com\u003c/url\u003e\n    \u003c/repository\u003e\n\u003c/repositories\u003e\n\n\u003cdependency\u003e\n    \u003cgroupId\u003eio.github.robwin\u003c/groupId\u003e\n    \u003cartifactId\u003eassertj-swagger\u003c/artifactId\u003e\n    \u003cversion\u003e{version}\u003c/version\u003e\n\u003c/dependency\u003e\n----\n\n==== Gradle\n\n[source,groovy, subs=\"attributes\"]\n----\nrepositories {\n    jcenter()\n}\n\ncompile \"io.github.robwin:assertj-swagger:{version}\"\n----\n\n=== Using assertj-swagger in an integration test\n\nUsing assertj-swagger is simple. For example, if you are using https://github.com/spring-projects/spring-boot[Spring Boot] and https://github.com/springfox/springfox[springfox] or https://github.com/swagger-api/swagger-core/wiki/Java-JAXRS-Quickstart[JAX-RS Swagger], you can validate your Swagger JSON in an integration test.\n\nThe following code sample shows how to validate an API using the Documentation Driven Contract test pattern:\n\n[source, java]\n----\n@RunWith(SpringJUnit4ClassRunner.class)\n@SpringApplicationConfiguration(classes = Application.class)\n@IntegrationTest\n@WebAppConfiguration\npublic class AssertjSwaggerDocumentationDrivenTest {\n    @Test\n    public void validateThatImplementationMatchesDocumentationSpecification(){\n        String designFirstSwagger = SwaggerAssertTest.class.getResource(\"/swagger.yaml\").getPath();\n        SwaggerAssertions.assertThat(\"http://localhost:8080/v2/api-docs\")\n            .isEqualTo(designFirstSwagger);\n    }\n}\n----\n\nThe following code sample shows how to validate an API using the Consumer Driven Contract test pattern:\n\n[source, java]\n----\n@RunWith(SpringJUnit4ClassRunner.class)\n@SpringApplicationConfiguration(classes = Application.class)\n@IntegrationTest\n@WebAppConfiguration\npublic class AssertjSwaggerConsumerDrivenTest {\n    @Test\n    public void validateThatImplementationSatisfiesConsumerSpecification(){\n        String designFirstSwagger = SwaggerAssertTest.class.getResource(\"/swagger-consumer1.yaml\").getPath();\n        SwaggerAssertions.assertThat(\"http://localhost:8080/v2/api-docs\")\n            .satisfiesContract(designFirstSwagger);\n    }\n}\n----\n\n==== Example output\n\nFor Documentation Driven Contract tests, Assertj-swagger fails a test if it finds differences between the implementation and the specification.\n\n[source]\n----\nThe following 4 assertions failed:\n1) [Checking Paths]\nExpecting:\n  \u003c[\"/api/pet\", \"/api/pet/findByStatus\", \"/api/pet/findByTags\", \"/api/pet/{petId}\", \"/api/store/order\", \"/api/store/order/{orderId}\", \"/api/user\", \"/api/user/createWithArray\", \"/api/user/createWithList\", \"/api/user/login\", \"/api/user/logout\", \"/api/user/{username}\"]\u003e\nto contain only:\n  \u003c[\"/pets\", \"/pets/findByStatus\", \"/pets/findByTags\", \"/pets/{petId}\", \"/stores/order\", \"/stores/order/{orderId}\", \"/users\", \"/users/createWithArray\", \"/users/createWithList\", \"/users/login\", \"/users/logout\", \"/users/{username}\"]\u003e\nelements not found:\n  \u003c[\"/pets/findByTags\", \"/users/logout\", \"/users\", \"/stores/order\", \"/users/createWithArray\", \"/pets\", \"/users/createWithList\", \"/pets/findByStatus\", \"/pets/{petId}\", \"/users/{username}\", \"/stores/order/{orderId}\", \"/users/login\"]\u003e\nand elements not expected:\n  \u003c[\"/api/store/order\", \"/api/user\", \"/api/user/createWithList\", \"/api/pet\", \"/api/pet/findByTags\", \"/api/user/createWithArray\", \"/api/user/login\", \"/api/pet/{petId}\", \"/api/store/order/{orderId}\", \"/api/user/{username}\", \"/api/pet/findByStatus\", \"/api/user/logout\"]\u003e\n\n2) [Checking properties of definition 'Order']\nExpecting:\n  \u003c[\"complete\", \"id\", \"identifier\", \"petId\", \"quantity\", \"shipDate\", \"status\"]\u003e\nto contain only:\n  \u003c[\"id\", \"petId\", \"quantity\", \"shipDate\", \"status\", \"complete\"]\u003e\nelements not found:\n  \u003c[]\u003e\nand elements not expected:\n  \u003c[\"identifier\"]\u003e\n\n3) [Checking properties of definition 'User']\nExpecting:\n  \u003c[\"email\", \"firstName\", \"id\", \"identifier\", \"lastName\", \"password\", \"phone\", \"userStatus\", \"username\"]\u003e\nto contain only:\n  \u003c[\"id\", \"username\", \"firstName\", \"lastName\", \"email\", \"password\", \"phone\", \"userStatus\"]\u003e\nelements not found:\n  \u003c[]\u003e\nand elements not expected:\n  \u003c[\"identifier\"]\u003e\n\n4) [Checking properties of definition 'Pet']\nExpecting:\n  \u003c[\"category\", \"id\", \"identifier\", \"name\", \"photoUrls\", \"status\", \"tags\"]\u003e\nto contain only:\n  \u003c[\"id\", \"category\", \"name\", \"photoUrls\", \"tags\", \"status\"]\u003e\nelements not found:\n  \u003c[]\u003e\nand elements not expected:\n  \u003c[\"identifier\"]\u003e\n----\n\nFor Consumer Driven Contract tests,  Assertj-swagger fails a test if it finds missing resources, methods, models, or properties in the implementation which are required by the consumer specification.\n\n[source]\n----\nThe following 4 assertions failed:\n1) [Checking Paths]\nExpecting:\n \u003c[\"/pets\", \"/pets/findByStatus\", \"/pets/findByTags\", \"/pets/{petId}\", \"/stores/order\", \"/stores/order/{orderId}\", \"/users\", \"/users/createWithArray\", \"/users/createWithList\", \"/users/login\", \"/users/logout\", \"/users/{username}\"]\u003e\nto contain:\n \u003c[\"/animals/{animalId}\", \"/pets\", \"/pets/findByStatus\", \"/pets/{petId}\"]\u003e\nbut could not find:\n \u003c[\"/animals/{animalId}\"]\u003e\n\n2) [Checking Definitions]\nExpecting:\n \u003c[\"User\", \"Category\", \"Pet\", \"Tag\", \"Order\"]\u003e\nto contain:\n \u003c[\"Category\", \"Pet\", \"Animal\", \"Tag\"]\u003e\nbut could not find:\n \u003c[\"Animal\"]\u003e\n\n3) [Checking properties of definition 'Pet']\nExpecting:\n \u003c[\"id\", \"category\", \"name\", \"photoUrls\", \"tags\", \"status\"]\u003e\nto contain:\n \u003c[\"photoUrls\", \"extraProperty\", \"name\", \"id\", \"category\", \"tags\", \"status\"]\u003e\nbut could not find:\n \u003c[\"extraProperty\"]\u003e\n\n4) [Checking property 'extraProperty' of definition 'Pet']\nExpecting actual not to be null\n----\n\n=== Using assertj-swagger in a unit test\n\nIf you are using the https://github.com/spring-projects/spring-framework[spring-framework] and https://github.com/springfox/springfox[springfox], Spring's MVC Test framework can also be used to validate the Swagger JSON output against your contract-first Swagger specification.\nThat way you can make sure that the implementation is in compliance with the design specification.\n\nThe following code sample shows how to write a unit test using the Documentation Driven Contract test pattern:\n\n[source, java]\n----\n@Test\npublic void validateThatImplementationFitsDesignSpecification() throws Exception {\n    String designFirstDocumentationSwaggerLocation = Swagger2MarkupTest.class.getResource(\"/swagger.yaml\").getPath();\n\n    MvcResult mvcResult = this.mockMvc.perform(get(\"/v2/api-docs\")\n            .accept(MediaType.APPLICATION_JSON))\n            .andExpect(status().isOk())\n            .andReturn();\n\n    String springfoxSwaggerJson = mvcResult.getResponse().getContentAsString();\n    SwaggerAssertions.assertThat(new SwaggerParser().parse(springfoxSwaggerJson)).isEqualTo(designFirstDocumentationSwaggerLocation);\n}\n----\n\nThe following code sample shows how to write a unit test using the Consumer Driven Contract test pattern:\n\n[source, java]\n----\n@Test\npublic void validateThatImplementationFitsDesignSpecification() throws Exception {\n    String designFirstConsumerSwaggerLocation = Swagger2MarkupTest.class.getResource(\"/swagger-consumer1.yaml\").getPath();\n\n    MvcResult mvcResult = this.mockMvc.perform(get(\"/v2/api-docs\")\n            .accept(MediaType.APPLICATION_JSON))\n            .andExpect(status().isOk())\n            .andReturn();\n\n    String springfoxSwaggerJson = mvcResult.getResponse().getContentAsString();\n    SwaggerAssertions.assertThat(new SwaggerParser().parse(springfoxSwaggerJson)).satisfiesContract(designFirstConsumerSwaggerLocation);\n}\n----\n\n=== Customizing assertj-swagger's behaviour\n\nFor most use cases, the default behaviour will be sufficient.  However, you can override the default behaviour in various ways by placing a Java property file, `/assertj-swagger.properties`, at the root of your classpath.  It is also possible to override the configuration in your tests; construct an instance of the `SwaggerAssert` class with a custom configuration if this is required.\n\nThe following overrides are available:\n\n==== Disable various types of checks which are enabled by default\n\n* `assertj.swagger.validateDefinitions=false`: disable all validation of definitions\n** `assertj.swagger.validateProperties=false`: disable validation of properties of definitions\n*** `assertj.swagger.validateRefProperties=false`: disable validation of reference (`$ref`) properties of definitions\n*** `assertj.swagger.validateArrayProperties=false`: disable validation of array properties of definitions\n*** `assertj.swagger.validateByteArrayProperties=false`: disable validation of byte-array properties of definitions\n*** `assertj.swagger.validateStringProperties=false`: disable validation of string properties of definitions\n** `assertj.swagger.validateModels=false`: disable validation of models\n* `assertj.swagger.validatePaths=false`: disable all validation of endpoint definitions\n* `assertj.swagger.validateResponseWithStrictlyMatch=false`: allow actual contract return extra return code\n\n==== Enable various types of checks which are disabled by default\n\nThe following settings are disabled by default, as they will cause schema comparisions to be too brittle for many users. They can be enabled if required.\n\n* `assertj.swagger.validateInfo=true`: enable comparison of the info section\n* `assertj.swagger.validateVersion=true`: enable comparison of the schema version numbers\n\n==== Disable checks for certain paths or definitions in 'actual' schema\n\nThis feature is useful in development situations, where you have written a contract-first schema by hand, and are validating a contract-last schema generated by a partially-implemented API.\n\nTo ignore unimplemented endpoints, try something like:\n\n[source]\n----\nassertj.swagger.pathsToIgnoreInExpected=\\\n   /v1/friends/{id},\\\n   /v1/groups/{groupId}\n----\n\nTo ignore unimplemented definitions, use something like:\n\n[source]\n----\nassertj.swagger.definitionsToIgnoreInExpected=\\\n   Foo,\\\n   Bar\n----\n\nTo ignore unimplemented properties, use something like:\n\n[source]\n----\nassertj.swagger.propertiesToIgnoreInExpected=\\\n   Foo.prop1,\\\n   Bar.prop2\n----\n\n\n==== Comparing expected and actual paths in schemas\n\nIt is occasionally useful to be able to compare schemas, where due to limitations in tools and libraries, endpoint\npaths don't align. Specifying a `basePath` setting in your design-first schema here won't work -- it's only used by\nSwagger tooling to generate paths at runtime, and does *not* form part of the logical pathname of your endpoints.\nFor instance, in your design-first schema, you may specify a set of endpoints and a `basePath`, while your generated\nschema (generated from, say, Springfox) has a common prefix prepended on the endpoint paths; e.g.:\n\n[source]\n----\n/pets/findByStatus       ! design-first schema\n----\n\nand\n\n[source]\n----\n/v2/pets/findByStatus    ! actual schema\n----\n\nTo ensure that assertj-swagger is comparing like-with-like in this situation, you could use the following in your\nconfiguration file:\n\n[source]\n----\nassertj.swagger.pathsPrependExpected=/v2\n----\n\n\n== License\n\nCopyright 2015 Robert Winkler\n\nLicensed under the Apache License, Version 2.0 (the \"License\"); you may not use this file except in compliance with the License. You may obtain a copy of the License at\n\n    http://www.apache.org/licenses/LICENSE-2.0\n\nUnless required by applicable law or agreed to in writing, software distributed under the License is distributed on an \"AS IS\" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frobwin%2Fassertj-swagger","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frobwin%2Fassertj-swagger","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frobwin%2Fassertj-swagger/lists"}