From f56a4d52ca4c9fa294f73bc9664267e7798eb2bc Mon Sep 17 00:00:00 2001 From: Kyle Lieber Date: Mon, 9 Oct 2023 14:38:01 -0500 Subject: [PATCH] chore(deps): update restdocs-api-spec to v0.19.0 Adds support for `contact` object in the mojo parameters. --- pom.xml | 2 +- .../restdocs/spec/ApiDetails.java | 13 ++++ .../restdocs/spec/Contact.java | 32 +++++++++ .../OpenApi30SpecificationGenerator.java | 9 ++- .../OpenApi30SpecificationGeneratorTest.java | 16 +++++ .../mock-specs/openapi2/default-settings.yml | 8 ++- .../resources/mock-specs/openapi3/contact.yml | 55 +++++++++++++++ .../mock-specs/openapi3/default-settings.yml | 4 ++ .../mock-specs/openapi3/host-with-port.yml | 4 ++ .../src/it/openapi-3.0/pom.xml | 62 +++++++++++++++++ .../snippets/cart-add-product/resource.json | 26 +++++++ .../snippets/cart-get/resource.json | 68 +++++++++++++++++++ .../snippets/cart-order/resource.json | 26 +++++++ .../snippets/carts-create/resource.json | 26 +++++++ .../src/it/openapi-3.0/verify.groovy | 1 + .../restdocs/mojo/AbstractGenerateMojo.java | 9 ++- 16 files changed, 355 insertions(+), 6 deletions(-) create mode 100644 restdocs-spec-generator/src/main/java/com/berkleytechnologyservices/restdocs/spec/Contact.java create mode 100644 restdocs-spec-generator/src/test/resources/mock-specs/openapi3/contact.yml create mode 100644 restdocs-spec-maven-plugin/src/it/openapi-3.0/pom.xml create mode 100644 restdocs-spec-maven-plugin/src/it/openapi-3.0/snippets/cart-add-product/resource.json create mode 100644 restdocs-spec-maven-plugin/src/it/openapi-3.0/snippets/cart-get/resource.json create mode 100644 restdocs-spec-maven-plugin/src/it/openapi-3.0/snippets/cart-order/resource.json create mode 100644 restdocs-spec-maven-plugin/src/it/openapi-3.0/snippets/carts-create/resource.json create mode 100644 restdocs-spec-maven-plugin/src/it/openapi-3.0/verify.groovy diff --git a/pom.xml b/pom.xml index 8c30986..59d1f92 100644 --- a/pom.xml +++ b/pom.xml @@ -55,7 +55,7 @@ 17 3.3.1 3.9.0 - 0.17.1 + 0.19.0 5.10.0 3.24.2 5.6.0 diff --git a/restdocs-spec-generator/src/main/java/com/berkleytechnologyservices/restdocs/spec/ApiDetails.java b/restdocs-spec-generator/src/main/java/com/berkleytechnologyservices/restdocs/spec/ApiDetails.java index 3856f8a..9593eb8 100644 --- a/restdocs-spec-generator/src/main/java/com/berkleytechnologyservices/restdocs/spec/ApiDetails.java +++ b/restdocs-spec-generator/src/main/java/com/berkleytechnologyservices/restdocs/spec/ApiDetails.java @@ -2,6 +2,7 @@ import java.util.Collections; import java.util.List; +import java.util.Optional; public class ApiDetails { @@ -20,6 +21,8 @@ public class ApiDetails { private SpecificationFormat format; private AuthConfig authConfig; private List tags; + + private Contact contact; public ApiDetails() { this.name = DEFAULT_NAME; @@ -30,6 +33,7 @@ public ApiDetails() { this.format = DEFAULT_FORMAT; this.authConfig = new AuthConfig(); this.tags = Collections.emptyList(); + this.contact = null; } public String getName() { @@ -112,4 +116,13 @@ public ApiDetails tags(List tags) { this.tags = tags != null ? tags : this.tags; return this; } + + public Optional getContact() { + return Optional.ofNullable(contact); + } + + public ApiDetails contact(Contact contact) { + this.contact = contact; + return this; + } } diff --git a/restdocs-spec-generator/src/main/java/com/berkleytechnologyservices/restdocs/spec/Contact.java b/restdocs-spec-generator/src/main/java/com/berkleytechnologyservices/restdocs/spec/Contact.java new file mode 100644 index 0000000..6fa22e6 --- /dev/null +++ b/restdocs-spec-generator/src/main/java/com/berkleytechnologyservices/restdocs/spec/Contact.java @@ -0,0 +1,32 @@ +package com.berkleytechnologyservices.restdocs.spec; + +public class Contact { + + private String name; + private String email; + private String url; + + public String getName() { + return name; + } + + public void setName(String name) { + this.name = name; + } + + public String getEmail() { + return email; + } + + public void setEmail(String email) { + this.email = email; + } + + public String getUrl() { + return url; + } + + public void setUrl(String url) { + this.url = url; + } +} diff --git a/restdocs-spec-generator/src/main/java/com/berkleytechnologyservices/restdocs/spec/generator/openapi_v3/OpenApi30SpecificationGenerator.java b/restdocs-spec-generator/src/main/java/com/berkleytechnologyservices/restdocs/spec/generator/openapi_v3/OpenApi30SpecificationGenerator.java index 370a7bc..5e9d4ce 100644 --- a/restdocs-spec-generator/src/main/java/com/berkleytechnologyservices/restdocs/spec/generator/openapi_v3/OpenApi30SpecificationGenerator.java +++ b/restdocs-spec-generator/src/main/java/com/berkleytechnologyservices/restdocs/spec/generator/openapi_v3/OpenApi30SpecificationGenerator.java @@ -1,6 +1,7 @@ package com.berkleytechnologyservices.restdocs.spec.generator.openapi_v3; import com.berkleytechnologyservices.restdocs.spec.ApiDetails; +import com.berkleytechnologyservices.restdocs.spec.Contact; import com.berkleytechnologyservices.restdocs.spec.Specification; import com.berkleytechnologyservices.restdocs.spec.generator.SpecificationGenerator; import com.berkleytechnologyservices.restdocs.spec.generator.SpecificationGeneratorException; @@ -43,7 +44,8 @@ public String generate(ApiDetails details, List models) throws Sp SpecificationGeneratorUtils.createTagDescriptionsMap(details.getTags()), details.getVersion(), SpecificationGeneratorUtils.createOauth2Configuration(details.getAuthConfig()), - details.getFormat().name().toLowerCase() + details.getFormat().name().toLowerCase(), + details.getContact().map(this::toSwaggerContact).orElse(null) ); } @@ -59,4 +61,9 @@ private List createServerList(ApiDetails details) throws SpecificationGe } return servers; } + + private io.swagger.v3.oas.models.info.Contact toSwaggerContact(Contact contact) { + io.swagger.v3.oas.models.info.Contact swaggerContact = new io.swagger.v3.oas.models.info.Contact(); + return swaggerContact.name(contact.getName()).email(contact.getEmail()).url(contact.getUrl()); + } } diff --git a/restdocs-spec-generator/src/test/java/com/berkleytechnologyservices/restdocs/spec/generator/openapi_v3/OpenApi30SpecificationGeneratorTest.java b/restdocs-spec-generator/src/test/java/com/berkleytechnologyservices/restdocs/spec/generator/openapi_v3/OpenApi30SpecificationGeneratorTest.java index c50fe6c..c1eac7c 100644 --- a/restdocs-spec-generator/src/test/java/com/berkleytechnologyservices/restdocs/spec/generator/openapi_v3/OpenApi30SpecificationGeneratorTest.java +++ b/restdocs-spec-generator/src/test/java/com/berkleytechnologyservices/restdocs/spec/generator/openapi_v3/OpenApi30SpecificationGeneratorTest.java @@ -1,6 +1,7 @@ package com.berkleytechnologyservices.restdocs.spec.generator.openapi_v3; import com.berkleytechnologyservices.restdocs.spec.ApiDetails; +import com.berkleytechnologyservices.restdocs.spec.Contact; import com.berkleytechnologyservices.restdocs.spec.Specification; import com.berkleytechnologyservices.restdocs.spec.generator.SpecificationGeneratorException; import com.epages.restdocs.apispec.model.HTTPMethod; @@ -49,6 +50,21 @@ public void testGenerateHostWithPort() throws SpecificationGeneratorException { .isEqualToNormalizingNewlines(contentOfResource("/mock-specs/openapi3/host-with-port.yml")); } + @Test + public void testGenerateContact() throws SpecificationGeneratorException { + Contact contact = new Contact(); + contact.setName("John Doe"); + contact.setEmail("john@example.com"); + contact.setUrl("https://john.example.com"); + + ApiDetails apiDetails = new ApiDetails().contact(contact); + + String rawOutput = generator.generate(apiDetails, list(getMockResource())); + + assertThat(rawOutput) + .isEqualToNormalizingNewlines(contentOfResource("/mock-specs/openapi3/contact.yml")); + } + private ResourceModel getMockResource() { return resource( "book-get", diff --git a/restdocs-spec-generator/src/test/resources/mock-specs/openapi2/default-settings.yml b/restdocs-spec-generator/src/test/resources/mock-specs/openapi2/default-settings.yml index 745073f..9caf24f 100644 --- a/restdocs-spec-generator/src/test/resources/mock-specs/openapi2/default-settings.yml +++ b/restdocs-spec-generator/src/test/resources/mock-specs/openapi2/default-settings.yml @@ -27,10 +27,14 @@ paths: description: "" examples: {} schema: - $ref: '#/definitions/book_id-1050330160' + $ref: '#/definitions/book_id-1528421121' definitions: - book_id-1050330160: + book_id-1528421121: type: object + required: + - author + - pages + - title properties: pages: type: number diff --git a/restdocs-spec-generator/src/test/resources/mock-specs/openapi3/contact.yml b/restdocs-spec-generator/src/test/resources/mock-specs/openapi3/contact.yml new file mode 100644 index 0000000..b7bd3e0 --- /dev/null +++ b/restdocs-spec-generator/src/test/resources/mock-specs/openapi3/contact.yml @@ -0,0 +1,55 @@ +openapi: 3.0.1 +info: + title: API Documentation + contact: + name: John Doe + url: https://john.example.com + email: john@example.com + version: 1.0.0 +servers: +- url: http://localhost +tags: [] +paths: + /book/{id}: + get: + tags: + - book + summary: Get a book by id + description: Get a book by id + operationId: book-get + parameters: + - name: id + in: path + description: The unique identifier for the book. + required: true + schema: + type: number + responses: + "200": + description: "200" + content: + application/hal+json: + schema: + $ref: '#/components/schemas/MyCustomSchemaName' + examples: + book-get: + value: The example response. +components: + schemas: + MyCustomSchemaName: + title: MyCustomSchemaName + required: + - author + - pages + - title + type: object + properties: + pages: + type: number + description: Number of pages in the book + author: + type: string + description: Author of the book + title: + type: string + description: Title of the book diff --git a/restdocs-spec-generator/src/test/resources/mock-specs/openapi3/default-settings.yml b/restdocs-spec-generator/src/test/resources/mock-specs/openapi3/default-settings.yml index 8ffd1f2..9a175e1 100644 --- a/restdocs-spec-generator/src/test/resources/mock-specs/openapi3/default-settings.yml +++ b/restdocs-spec-generator/src/test/resources/mock-specs/openapi3/default-settings.yml @@ -34,6 +34,10 @@ components: schemas: MyCustomSchemaName: title: MyCustomSchemaName + required: + - author + - pages + - title type: object properties: pages: diff --git a/restdocs-spec-generator/src/test/resources/mock-specs/openapi3/host-with-port.yml b/restdocs-spec-generator/src/test/resources/mock-specs/openapi3/host-with-port.yml index 09f4cbf..a241c92 100644 --- a/restdocs-spec-generator/src/test/resources/mock-specs/openapi3/host-with-port.yml +++ b/restdocs-spec-generator/src/test/resources/mock-specs/openapi3/host-with-port.yml @@ -34,6 +34,10 @@ components: schemas: MyCustomSchemaName: title: MyCustomSchemaName + required: + - author + - pages + - title type: object properties: pages: diff --git a/restdocs-spec-maven-plugin/src/it/openapi-3.0/pom.xml b/restdocs-spec-maven-plugin/src/it/openapi-3.0/pom.xml new file mode 100644 index 0000000..473801f --- /dev/null +++ b/restdocs-spec-maven-plugin/src/it/openapi-3.0/pom.xml @@ -0,0 +1,62 @@ + + + 4.0.0 + + com.github.berkleytechnologyservices.restdocs-spec.it + default-settings-it + 1.0-SNAPSHOT + + Verify the default settings. + + + UTF-8 + + + + + + maven-resources-plugin + 3.3.1 + + + copy-resources + validate + + copy-resources + + + ${project.basedir}/target/generated-snippets + + + snippets + false + + + + + + + + @project.groupId@ + @project.artifactId@ + @project.version@ + + + + generate + + + OPENAPI_V3 + + John Doe + john@example.com + https://john.example.com + + + + + + + + diff --git a/restdocs-spec-maven-plugin/src/it/openapi-3.0/snippets/cart-add-product/resource.json b/restdocs-spec-maven-plugin/src/it/openapi-3.0/snippets/cart-add-product/resource.json new file mode 100644 index 0000000..6615b0a --- /dev/null +++ b/restdocs-spec-maven-plugin/src/it/openapi-3.0/snippets/cart-add-product/resource.json @@ -0,0 +1,26 @@ +{ + "operationId" : "cart-add-product", + "summary" : "Add products to a cart", + "description" : "Add products to a cart", + "privateResource" : false, + "deprecated" : false, + "request" : { + "path" : "/carts/{id}/products", + "method" : "POST", + "contentType" : "text/uri-list", + "headers" : [ ], + "pathParameters" : [ ], + "queryParameters" : [ ], + "formParameters" : [ ], + "requestFields" : [ ], + "example" : "http://localhost/products/1", + "securityRequirements" : null + }, + "response" : { + "status" : 200, + "contentType" : "application/hal+json", + "headers" : [ ], + "responseFields" : [ ], + "example" : "{\r\n \"total\" : 49.99,\r\n \"products\" : [ {\r\n \"quantity\" : 1,\r\n \"product\" : {\r\n \"name\" : \"Fancy pants\",\r\n \"price\" : 49.99\r\n },\r\n \"_links\" : {\r\n \"product\" : {\r\n \"href\" : \"http://localhost:8080/products/1\"\r\n }\r\n }\r\n } ],\r\n \"_links\" : {\r\n \"self\" : {\r\n \"href\" : \"http://localhost:8080/carts/1\"\r\n },\r\n \"order\" : {\r\n \"href\" : \"http://localhost:8080/carts/1/order\"\r\n }\r\n }\r\n}" + } +} \ No newline at end of file diff --git a/restdocs-spec-maven-plugin/src/it/openapi-3.0/snippets/cart-get/resource.json b/restdocs-spec-maven-plugin/src/it/openapi-3.0/snippets/cart-get/resource.json new file mode 100644 index 0000000..504f788 --- /dev/null +++ b/restdocs-spec-maven-plugin/src/it/openapi-3.0/snippets/cart-get/resource.json @@ -0,0 +1,68 @@ +{ + "operationId" : "cart-get", + "summary" : "Get a cart by id", + "description" : "Get a cart by id", + "privateResource" : false, + "deprecated" : false, + "request" : { + "path" : "/carts/{id}", + "method" : "GET", + "contentType" : null, + "headers" : [ ], + "pathParameters" : [ { + "name" : "id", + "description" : "the cart id", + "ignored" : false, + "type" : "STRING", + "optional" : false + } ], + "queryParameters" : [ ], + "formParameters" : [ ], + "requestFields" : [ ], + "example" : null, + "securityRequirements" : null + }, + "response" : { + "status" : 200, + "contentType" : "application/hal+json", + "headers" : [ ], + "responseFields" : [ { + "description" : "Total amount of the cart.", + "ignored" : false, + "path" : "total", + "type" : "NUMBER", + "optional" : false + }, { + "description" : "The product line item of the cart.", + "ignored" : false, + "path" : "products", + "type" : "ARRAY", + "optional" : false + }, { + "description" : "Link to the product.", + "ignored" : false, + "path" : "products[]._links.product", + "type" : "OBJECT", + "optional" : false + }, { + "description" : "The quantity of the line item.", + "ignored" : false, + "path" : "products[].quantity", + "type" : "NUMBER", + "optional" : false + }, { + "description" : "The product the line item relates to.", + "ignored" : false, + "path" : "products[].product", + "type" : "OBJECT", + "optional" : false + }, { + "description" : "Links section.", + "ignored" : false, + "path" : "_links", + "type" : "OBJECT", + "optional" : false + } ], + "example" : "{\r\n \"total\" : 49.99,\r\n \"products\" : [ {\r\n \"quantity\" : 1,\r\n \"product\" : {\r\n \"name\" : \"Fancy pants\",\r\n \"price\" : 49.99\r\n },\r\n \"_links\" : {\r\n \"product\" : {\r\n \"href\" : \"http://localhost:8080/products/2\"\r\n }\r\n }\r\n } ],\r\n \"_links\" : {\r\n \"self\" : {\r\n \"href\" : \"http://localhost:8080/carts/2\"\r\n },\r\n \"order\" : {\r\n \"href\" : \"http://localhost:8080/carts/2/order\"\r\n }\r\n }\r\n}" + } +} \ No newline at end of file diff --git a/restdocs-spec-maven-plugin/src/it/openapi-3.0/snippets/cart-order/resource.json b/restdocs-spec-maven-plugin/src/it/openapi-3.0/snippets/cart-order/resource.json new file mode 100644 index 0000000..675ea8f --- /dev/null +++ b/restdocs-spec-maven-plugin/src/it/openapi-3.0/snippets/cart-order/resource.json @@ -0,0 +1,26 @@ +{ + "operationId" : "cart-order", + "summary" : "Order a cart", + "description" : "Order a cart", + "privateResource" : false, + "deprecated" : false, + "request" : { + "path" : "/carts/{id}/order", + "method" : "POST", + "contentType" : null, + "headers" : [ ], + "pathParameters" : [ ], + "queryParameters" : [ ], + "formParameters" : [ ], + "requestFields" : [ ], + "example" : null, + "securityRequirements" : null + }, + "response" : { + "status" : 200, + "contentType" : "application/hal+json", + "headers" : [ ], + "responseFields" : [ ], + "example" : "{\r\n \"total\" : 49.99,\r\n \"products\" : [ {\r\n \"quantity\" : 1,\r\n \"product\" : {\r\n \"name\" : \"Fancy pants\",\r\n \"price\" : 49.99\r\n },\r\n \"_links\" : {\r\n \"product\" : {\r\n \"href\" : \"http://localhost:8080/products/3\"\r\n }\r\n }\r\n } ],\r\n \"_links\" : {\r\n \"self\" : {\r\n \"href\" : \"http://localhost:8080/carts/3\"\r\n }\r\n }\r\n}" + } +} \ No newline at end of file diff --git a/restdocs-spec-maven-plugin/src/it/openapi-3.0/snippets/carts-create/resource.json b/restdocs-spec-maven-plugin/src/it/openapi-3.0/snippets/carts-create/resource.json new file mode 100644 index 0000000..7a5363e --- /dev/null +++ b/restdocs-spec-maven-plugin/src/it/openapi-3.0/snippets/carts-create/resource.json @@ -0,0 +1,26 @@ +{ + "operationId" : "carts-create", + "summary" : "Create a cart", + "description" : "Create a cart", + "privateResource" : false, + "deprecated" : false, + "request" : { + "path" : "/carts", + "method" : "POST", + "contentType" : null, + "headers" : [ ], + "pathParameters" : [ ], + "queryParameters" : [ ], + "formParameters" : [ ], + "requestFields" : [ ], + "example" : null, + "securityRequirements" : null + }, + "response" : { + "status" : 201, + "contentType" : "application/hal+json", + "headers" : [ ], + "responseFields" : [ ], + "example" : "{\r\n \"total\" : 0,\r\n \"products\" : [ ],\r\n \"_links\" : {\r\n \"self\" : {\r\n \"href\" : \"http://localhost:8080/carts/4\"\r\n },\r\n \"order\" : {\r\n \"href\" : \"http://localhost:8080/carts/4/order\"\r\n }\r\n }\r\n}" + } +} \ No newline at end of file diff --git a/restdocs-spec-maven-plugin/src/it/openapi-3.0/verify.groovy b/restdocs-spec-maven-plugin/src/it/openapi-3.0/verify.groovy new file mode 100644 index 0000000..d0333f3 --- /dev/null +++ b/restdocs-spec-maven-plugin/src/it/openapi-3.0/verify.groovy @@ -0,0 +1 @@ +assert new File(basedir, "target/restdocs-spec/openapi-3.0.yml").exists() : 'Spec file was not found at the expected location' \ No newline at end of file diff --git a/restdocs-spec-maven-plugin/src/main/java/com/berkleytechnologyservices/restdocs/mojo/AbstractGenerateMojo.java b/restdocs-spec-maven-plugin/src/main/java/com/berkleytechnologyservices/restdocs/mojo/AbstractGenerateMojo.java index 5e1f692..ed341cd 100644 --- a/restdocs-spec-maven-plugin/src/main/java/com/berkleytechnologyservices/restdocs/mojo/AbstractGenerateMojo.java +++ b/restdocs-spec-maven-plugin/src/main/java/com/berkleytechnologyservices/restdocs/mojo/AbstractGenerateMojo.java @@ -2,6 +2,7 @@ import com.berkleytechnologyservices.restdocs.spec.ApiDetails; import com.berkleytechnologyservices.restdocs.spec.AuthConfig; +import com.berkleytechnologyservices.restdocs.spec.Contact; import com.berkleytechnologyservices.restdocs.spec.Specification; import com.berkleytechnologyservices.restdocs.spec.SpecificationFormat; import com.berkleytechnologyservices.restdocs.spec.Tag; @@ -114,6 +115,9 @@ public abstract class AbstractGenerateMojo extends AbstractMojo { @Parameter private List tags; + @Parameter + private Contact contact; + private final SpecificationGeneratorFactory specificationGeneratorFactory; @Inject @@ -202,13 +206,14 @@ private ApiDetails createApiDetails(SpecificationOptions options) { return new ApiDetails() .name(name) .version(version) - .description(description) + .description(description) .host(host) .basePath(basePath) .schemes(schemes) .format(options.getFormat()) .authConfig(oauth2) - .tags(tags); + .tags(tags) + .contact(contact); } private List getAllSpecificationOptions() {