diff --git a/src/main/java/io/openapitools/swagger/OutputFormat.java b/src/main/java/io/openapitools/swagger/OutputFormat.java index dc49931..b1eeb77 100644 --- a/src/main/java/io/openapitools/swagger/OutputFormat.java +++ b/src/main/java/io/openapitools/swagger/OutputFormat.java @@ -1,12 +1,15 @@ package io.openapitools.swagger; +import java.io.File; +import java.io.IOException; + import com.fasterxml.jackson.databind.ObjectMapper; import com.fasterxml.jackson.databind.SerializationFeature; +import io.openapitools.swagger.config.SwaggerServerVariable; import io.swagger.v3.core.util.Json; import io.swagger.v3.core.util.Yaml; import io.swagger.v3.oas.models.OpenAPI; -import java.io.File; -import java.io.IOException; +import io.swagger.v3.oas.models.servers.ServerVariable; /** * Supported output formats. @@ -42,6 +45,7 @@ static class JSONWriter implements SwaggerWriter { @Override public void write(OpenAPI swagger, File file, boolean prettyPrint) throws IOException { ObjectMapper mapper = Json.mapper(); + mapper.addMixIn(ServerVariable.class, SwaggerServerVariable.ServerVariableMixin.class); if (prettyPrint) { mapper.enable(SerializationFeature.INDENT_OUTPUT); } @@ -56,7 +60,9 @@ static class YAMLWriter implements SwaggerWriter { @Override public void write(OpenAPI swagger, File file, boolean prettyPrint) throws IOException { - Yaml.mapper().writeValue(file, swagger); + ObjectMapper mapper = Yaml.mapper(); + mapper.addMixIn(ServerVariable.class, SwaggerServerVariable.ServerVariableMixin.class); + mapper.writeValue(file, swagger); } } } diff --git a/src/main/java/io/openapitools/swagger/config/SwaggerComponents.java b/src/main/java/io/openapitools/swagger/config/SwaggerComponents.java new file mode 100644 index 0000000..56c77e7 --- /dev/null +++ b/src/main/java/io/openapitools/swagger/config/SwaggerComponents.java @@ -0,0 +1,29 @@ +package io.openapitools.swagger.config; + +import java.util.Map; + +import org.apache.maven.plugins.annotations.Parameter; + +import io.swagger.v3.oas.models.Components; + +public class SwaggerComponents { + + /** + * Security schemes (under Comtonents) + */ + @Parameter + private Map securitySchemes; + + // TODO: implement schemas, responses, ... from + // https://github.com/OAI/OpenAPI-Specification/blob/3.0.1/versions/3.0.1.md#componentsObject + + public Components createComponentsModel() { + Components components = new Components(); + + if (securitySchemes != null && !securitySchemes.isEmpty()) { + securitySchemes.entrySet().forEach(s -> components.addSecuritySchemes(s.getKey(), s.getValue().createSecuritySchemaModel())); + } + + return components; + } +} diff --git a/src/main/java/io/openapitools/swagger/config/SwaggerConfig.java b/src/main/java/io/openapitools/swagger/config/SwaggerConfig.java index cb7aaa2..f3d33fe 100644 --- a/src/main/java/io/openapitools/swagger/config/SwaggerConfig.java +++ b/src/main/java/io/openapitools/swagger/config/SwaggerConfig.java @@ -1,44 +1,88 @@ package io.openapitools.swagger.config; +import io.swagger.v3.oas.annotations.ExternalDocumentation; +import io.swagger.v3.oas.annotations.Parameters; import io.swagger.v3.oas.models.OpenAPI; import io.swagger.v3.oas.models.info.Info; import java.io.File; import java.io.IOException; import java.nio.file.Files; -import java.util.Arrays; import java.util.Collections; import java.util.List; +import java.util.Map; import java.util.stream.Collectors; import org.apache.maven.plugins.annotations.Parameter; /** - * Configuring Swagger in compliance with the way the com.github.kongchen Swagger plugin does it. + * Configuring Swagger in compliance with the way the com.github.kongchen + * Swagger plugin does it. */ public class SwaggerConfig { /** - * List of servers for the endpoint. + * REQUIRED. Provides metadata about the API. The metadata MAY be used by + * tooling as required. + * + * This might be overridden by ReaderListener or SwaggerDefinition annotation. + */ + @Parameter + private SwaggerInfo info; + + /** + * Convenience for reading the informational description from file instead of + * embedding it. + */ + @Parameter + private File descriptionFile; + + /** + * An array of Server Objects, which provide connectivity information to a + * target server. If the servers property is not provided, or is an empty array, + * the default value would be a Server Object with a url value of /. */ @Parameter private List servers = Collections.emptyList(); /** - * Providing the OpenAPI information description. This might be overridden by ReaderListener or SwaggerDefinition annotation. + * An element to hold various schemas for the specification. */ @Parameter - private SwaggerInfo info; + private SwaggerComponents components; /** - * Convenience for reading the informational description from file instead of embedding it. + * A declaration of which security mechanisms can be used across the API. The + * list of values includes alternative security requirement objects that can be + * used. Only one of the security requirement objects need to be satisfied to + * authorize a request. Individual operations can override this definition. */ @Parameter - private File descriptionFile; + private List securityRequirements = Collections.emptyList();; + + /** + * A list of tags used by the specification with additional metadata. The order + * of the tags can be used to reflect on their order by the parsing tools. Not + * all tags that are used by the Operation Object must be declared. The tags + * that are not declared MAY be organized randomly or based on the tools' logic. + * Each tag name in the list MUST be unique. + */ + @Parameter + private List tags = Collections.emptyList();; + + /** + * Additional external documentation. + */ + @Parameter + private SwaggerExternalDoc externalDoc; + + /** + * Providing extension attributes to the OpenAPI spec. + */ + @Parameter + private Map extensions = Collections.emptyMap(); public OpenAPI createSwaggerModel() { OpenAPI spec = new OpenAPI(); - servers.forEach(s -> spec.addServersItem(s.createServerModel())); - if (info != null) { spec.setInfo(info.createInfoModel()); } @@ -48,12 +92,26 @@ public OpenAPI createSwaggerModel() { spec.setInfo(new Info()); } try { - spec.getInfo().setDescription(Files.readAllLines(descriptionFile.toPath()).stream().collect(Collectors.joining("\n"))); + spec.getInfo().setDescription( + Files.readAllLines(descriptionFile.toPath()).stream().collect(Collectors.joining("\n"))); } catch (IOException e) { throw new RuntimeException("Unable to read descriptor file " + descriptionFile, e); } } + if (components != null) { + spec.setComponents(components.createComponentsModel()); + } + + if (externalDoc != null) { + spec.setExternalDocs(externalDoc.createExternalDocModel()); + } + + spec.setExtensions(extensions); + servers.forEach(s -> spec.addServersItem(s.createServerModel())); + securityRequirements.forEach(s -> spec.addSecurityItem(s.createSecurityModel())); + tags.forEach(t -> spec.addTagsItem(t.createTagModel())); + return spec; } } diff --git a/src/main/java/io/openapitools/swagger/config/SwaggerContact.java b/src/main/java/io/openapitools/swagger/config/SwaggerContact.java index f01dc21..a3f46eb 100644 --- a/src/main/java/io/openapitools/swagger/config/SwaggerContact.java +++ b/src/main/java/io/openapitools/swagger/config/SwaggerContact.java @@ -1,6 +1,10 @@ package io.openapitools.swagger.config; import io.swagger.v3.oas.models.info.Contact; + +import java.util.Collections; +import java.util.Map; + import org.apache.maven.plugins.annotations.Parameter; /** @@ -8,15 +12,27 @@ */ public class SwaggerContact { + /** + * The identifying name of the contact person/organization. + */ @Parameter private String name; + /** + * The URL pointing to the contact information. MUST be in the format of a URL. + */ @Parameter private String url; + /** + * The email address of the contact person/organization. MUST be in the format of an email address. + */ @Parameter private String email; + @Parameter + private Map extensions = Collections.emptyMap(); + public Contact createContactModel() { Contact contact = new Contact(); @@ -32,6 +48,8 @@ public Contact createContactModel() { contact.setEmail(email); } + contact.setExtensions(extensions); + return contact; } } diff --git a/src/main/java/io/openapitools/swagger/config/SwaggerExternalDoc.java b/src/main/java/io/openapitools/swagger/config/SwaggerExternalDoc.java new file mode 100644 index 0000000..6862cea --- /dev/null +++ b/src/main/java/io/openapitools/swagger/config/SwaggerExternalDoc.java @@ -0,0 +1,45 @@ +package io.openapitools.swagger.config; + +import java.util.Collections; +import java.util.Map; + +import org.apache.maven.plugins.annotations.Parameter; + +import io.swagger.v3.oas.models.ExternalDocumentation; + +public class SwaggerExternalDoc { + + /** + * A short description of the target documentation. CommonMark syntax MAY be + * used for rich text representation. + */ + @Parameter + private String description; + + /** + * REQUIRED. The URL for the target documentation. Value MUST be in the format + * of a URL. + */ + @Parameter(required = true) + private String url; + + @Parameter + private Map extensions = Collections.emptyMap(); + + public ExternalDocumentation createExternalDocModel() { + ExternalDocumentation externalDoc = new ExternalDocumentation(); + + if (description != null) { + externalDoc.setDescription(description); + } + + if (url != null) { + externalDoc.setUrl(url); + } + + externalDoc.setExtensions(extensions); + + return externalDoc; + } + +} diff --git a/src/main/java/io/openapitools/swagger/config/SwaggerFlows.java b/src/main/java/io/openapitools/swagger/config/SwaggerFlows.java new file mode 100644 index 0000000..4c95256 --- /dev/null +++ b/src/main/java/io/openapitools/swagger/config/SwaggerFlows.java @@ -0,0 +1,106 @@ +package io.openapitools.swagger.config; + +import java.util.Collections; +import java.util.Map; + +import io.swagger.v3.oas.annotations.Parameter; +import io.swagger.v3.oas.models.security.OAuthFlow; +import io.swagger.v3.oas.models.security.OAuthFlows; +import io.swagger.v3.oas.models.security.Scopes; + +public class SwaggerFlows { + + /** + * Configuration for the OAuth Implicit flow + */ + @Parameter + private Entry implicit; + + /** + * Configuration for the OAuth Resource Owner Password flow + */ + @Parameter + private Entry password; + + /** + * Configuration for the OAuth Client Credentials flow. Previously called + * application in OpenAPI 2.0. + */ + @Parameter + private Entry clientCredentials; + + /** + * Configuration for the OAuth Authorization Code flow. Previously called + * accessCode in OpenAPI 2.0. + */ + @Parameter + private Entry authorizationCode; + + @Parameter + private Map extensions = Collections.emptyMap(); + + public OAuthFlows createOAuthFlowsModel() { + OAuthFlows flows = new OAuthFlows(); + if (implicit != null) { + flows.setImplicit(implicit.toOAuthFlowModel()); + } + if (password != null) { + flows.setPassword(password.toOAuthFlowModel()); + } + if (clientCredentials != null) { + flows.setClientCredentials(clientCredentials.toOAuthFlowModel()); + } + if (authorizationCode != null) { + flows.setAuthorizationCode(authorizationCode.toOAuthFlowModel()); + } + flows.setExtensions(extensions); + return flows; + } + + public static class Entry { + /** + * For implicit/authorizationCode flows: REQUIRED. The authorization URL to be used for this flow. This MUST be in the form of a URL. + */ + @Parameter + private String authorizationUrl; + + /** + * For password/clientCredentials/AuthorizationCode flows: REQUIRED. The token URL to be used for this flow. This MUST be in the form of a URL. + */ + @Parameter + private String tokenUrl; + + /** + * The URL to be used for obtaining refresh tokens. This MUST be in the form of a URL. + */ + @Parameter + private String refreshUrl; + + /** + * REQUIRED. The available scopes for the OAuth2 security scheme. A map between the scope name and a short description for it. + */ + @Parameter(required = true) + private Map scopes = Collections.emptyMap(); + + @Parameter + private Map extensions = Collections.emptyMap(); + + public OAuthFlow toOAuthFlowModel() { + OAuthFlow flow = new OAuthFlow(); + + flow.setAuthorizationUrl(authorizationUrl); + flow.setTokenUrl(tokenUrl); + flow.setRefreshUrl(refreshUrl); + if (scopes != null && !scopes.isEmpty()) { + Scopes ss = new Scopes(); + scopes.entrySet().forEach(s -> ss.addString(s.getKey(), s.getValue())); + flow.setScopes(ss); + } + + if (extensions != null && !extensions.isEmpty()) { + flow.setExtensions(extensions); + } + return flow; + } + } +} diff --git a/src/main/java/io/openapitools/swagger/config/SwaggerInfo.java b/src/main/java/io/openapitools/swagger/config/SwaggerInfo.java index 07e02c8..826fcc8 100644 --- a/src/main/java/io/openapitools/swagger/config/SwaggerInfo.java +++ b/src/main/java/io/openapitools/swagger/config/SwaggerInfo.java @@ -9,21 +9,41 @@ */ public class SwaggerInfo { - @Parameter + /** + * REQUIRED. The title of the application. + */ + @Parameter(required = true) private String title; - @Parameter + /** + * REQUIRED. The version of the OpenAPI document (which is distinct from the + * OpenAPI Specification version or the API implementation version). + */ + @Parameter(required = true) private String version; + /** + * A short description of the application. CommonMark syntax MAY be used for + * rich text representation. + */ @Parameter private String description; + /** + * A URL to the Terms of Service for the API. MUST be in the format of a URL. + */ @Parameter private String termsOfService; + /** + * The contact information for the exposed API. + */ @Parameter private SwaggerContact contact; + /** + * The license information for the exposed API. + */ @Parameter private SwaggerLicense license; diff --git a/src/main/java/io/openapitools/swagger/config/SwaggerLicense.java b/src/main/java/io/openapitools/swagger/config/SwaggerLicense.java index 3af0dbb..0da7bfa 100644 --- a/src/main/java/io/openapitools/swagger/config/SwaggerLicense.java +++ b/src/main/java/io/openapitools/swagger/config/SwaggerLicense.java @@ -1,6 +1,10 @@ package io.openapitools.swagger.config; import io.swagger.v3.oas.models.info.License; + +import java.util.Collections; +import java.util.Map; + import org.apache.maven.plugins.annotations.Parameter; /** @@ -8,11 +12,20 @@ */ public class SwaggerLicense { - @Parameter + /** + * REQUIRED. The license name used for the API. + */ + @Parameter(required = true) private String name; + /** + * A URL to the license used for the API. MUST be in the format of a URL. + */ @Parameter private String url; + + @Parameter + private Map extensions = Collections.emptyMap(); public License createLicenseModel() { License license = new License(); @@ -24,6 +37,8 @@ public License createLicenseModel() { if (url != null) { license.setUrl(url); } + + license.setExtensions(extensions); return license; } diff --git a/src/main/java/io/openapitools/swagger/config/SwaggerSecurityRequirement.java b/src/main/java/io/openapitools/swagger/config/SwaggerSecurityRequirement.java new file mode 100644 index 0000000..5ebe393 --- /dev/null +++ b/src/main/java/io/openapitools/swagger/config/SwaggerSecurityRequirement.java @@ -0,0 +1,40 @@ +package io.openapitools.swagger.config; + +import java.util.Collections; +import java.util.List; + +import org.apache.maven.plugins.annotations.Parameter; + +import io.swagger.v3.oas.models.security.SecurityRequirement; + +public class SwaggerSecurityRequirement { + + /** + * Each name MUST correspond to a security scheme which is declared in the + * Security Schemes under the Components Object. If the security scheme is of + * type "oauth2" or "openIdConnect", then the value is a list of scope names + * required for the execution. For other security scheme types, the array MUST + * be empty. + */ + @Parameter + private List entries = Collections.emptyList(); + + public SecurityRequirement createSecurityModel() { + if (entries == null || entries.isEmpty()) { + return null; + } + + SecurityRequirement securityReq = new SecurityRequirement(); + entries.forEach(e -> securityReq.addList(e.name, e.list)); + return securityReq; + } + + public static class Entry { + + @Parameter(required = true) + private String name; + + @Parameter + private List list = Collections.emptyList(); + } +} diff --git a/src/main/java/io/openapitools/swagger/config/SwaggerSecurityScheme.java b/src/main/java/io/openapitools/swagger/config/SwaggerSecurityScheme.java new file mode 100644 index 0000000..a77d394 --- /dev/null +++ b/src/main/java/io/openapitools/swagger/config/SwaggerSecurityScheme.java @@ -0,0 +1,103 @@ +package io.openapitools.swagger.config; + +import java.util.Map; + +import org.apache.maven.plugins.annotations.Parameter; + +import io.swagger.v3.oas.models.security.SecurityScheme; +import io.swagger.v3.oas.models.security.SecurityScheme.In; +import io.swagger.v3.oas.models.security.SecurityScheme.Type; + +public class SwaggerSecurityScheme { + + /** + * REQUIRED. The type of the security scheme. Valid values are "apiKey", "http", + * "oauth2", "openIdConnect". + */ + @Parameter + private String type; + + /** + * A short description for security scheme. CommonMark syntax MAY be used for + * rich text representation. + */ + @Parameter + private String description; + + /** + * If type is apiKey: REQUIRED. The name of the header, query or cookie + * parameter to be used. + */ + @Parameter + private String name; + + /** + * If type is apiKey: REQUIRED. The location of the API key. Valid values are + * "query", "header" or "cookie". + */ + @Parameter + private String in; + + /** + * If type is http: REQUIRED. The name of the HTTP Authorization scheme to be + * used in the Authorization header as defined in RFC7235. + */ + @Parameter + private String scheme; + + /** + * If type is http/"bearer": A hint to the client to identify how the bearer + * token is formatted. Bearer tokens are usually generated by an authorization + * server, so this information is primarily for documentation purposes. + */ + @Parameter + private String bearerFormat; + + /** + * If type is oauth2: REQUIRED. An object containing configuration information + * for the flow types supported. + */ + @Parameter + private SwaggerFlows flows; + + /** + * If type is openIdConnect: REQUIRED. OpenId Connect URL to discover OAuth2 + * configuration values. This MUST be in the form of a URL. + */ + @Parameter + private String openIdConnectUrl; + + @Parameter + private Map extensions; + + @Parameter + private String $ref; + + public SecurityScheme createSecuritySchemaModel() { + SecurityScheme securityScheme = new SecurityScheme(); + + if (type != null) { + securityScheme.setType(Type.valueOf(type.toUpperCase())); + } + securityScheme.setDescription(description); + securityScheme.setName(name); + if (in != null) { + securityScheme.setIn(In.valueOf(in.toUpperCase())); + } + securityScheme.setScheme(scheme); + securityScheme.setBearerFormat(bearerFormat); + if (flows != null) { + securityScheme.setFlows(flows.createOAuthFlowsModel()); + } + securityScheme.setOpenIdConnectUrl(openIdConnectUrl); + + if (extensions != null && !extensions.isEmpty()) { + securityScheme.setExtensions(extensions); + } + + // Alternative to setting all above properties: reference to other component + securityScheme.set$ref($ref); + + return securityScheme; + } +} diff --git a/src/main/java/io/openapitools/swagger/config/SwaggerServer.java b/src/main/java/io/openapitools/swagger/config/SwaggerServer.java index db95982..9cc7761 100644 --- a/src/main/java/io/openapitools/swagger/config/SwaggerServer.java +++ b/src/main/java/io/openapitools/swagger/config/SwaggerServer.java @@ -1,20 +1,55 @@ package io.openapitools.swagger.config; import io.swagger.v3.oas.models.servers.Server; +import io.swagger.v3.oas.models.servers.ServerVariables; + +import java.util.Collections; +import java.util.Map; + import org.apache.maven.plugins.annotations.Parameter; public class SwaggerServer { - @Parameter + /** + * REQUIRED. A URL to the target host. This URL supports Server Variables and + * MAY be relative, to indicate that the host location is relative to the + * location where the OpenAPI document is being served. Variable substitutions + * will be made when a variable is named in {brackets}. + */ + @Parameter(required = true) private String url; + /** + * An optional string describing the host designated by the URL. CommonMark + * syntax MAY be used for rich text representation. + */ @Parameter private String description; + /** + * A map between a variable name and its value. The value is used for + * substitution in the server's URL template. + */ + @Parameter + private Map variables = Collections.emptyMap(); + + @Parameter + private Map extensions = Collections.emptyMap(); + public Server createServerModel() { Server server = new Server(); server.setUrl(url); server.setDescription(description); + + if (variables != null && !variables.isEmpty()) { + ServerVariables vs = new ServerVariables(); + variables.entrySet() + .forEach(v -> vs.addServerVariable(v.getKey(), v.getValue().createServerVariableModel())); + server.setVariables(vs); + } + + server.setExtensions(extensions); + return server; } diff --git a/src/main/java/io/openapitools/swagger/config/SwaggerServerVariable.java b/src/main/java/io/openapitools/swagger/config/SwaggerServerVariable.java new file mode 100644 index 0000000..49abcd2 --- /dev/null +++ b/src/main/java/io/openapitools/swagger/config/SwaggerServerVariable.java @@ -0,0 +1,61 @@ +package io.openapitools.swagger.config; + +import java.util.Collections; +import java.util.List; +import java.util.Map; + +import com.fasterxml.jackson.annotation.JsonAnyGetter; +import com.fasterxml.jackson.annotation.JsonPropertyOrder; +import io.swagger.v3.oas.models.servers.ServerVariable; +import org.apache.maven.plugins.annotations.Parameter; + +public class SwaggerServerVariable { + + /** + * REQUIRED. The default value to use for substitution, and to send, if an + * alternate value is not supplied. Unlike the Schema Object's default, this + * value MUST be provided by the consumer. + */ + @Parameter(required = true) + private String defaultValue; + + /** + * An enumeration of string values to be used if the substitution options are + * from a limited set. + */ + @Parameter + private List enumValues = Collections.emptyList(); + + /** + * An optional description for the server variable. CommonMark syntax MAY be + * used for rich text representation. + */ + @Parameter + private String description; + + @Parameter + private Map extensions; + + public ServerVariable createServerVariableModel() { + ServerVariable serverVar = new ServerVariable(); + + serverVar.setDefault(defaultValue); + if (enumValues != null && !enumValues.isEmpty()) { + serverVar.setEnum(enumValues); + } + serverVar.setDescription(description); + + if (extensions != null && !extensions.isEmpty()) { + serverVar.setExtensions(extensions); + } + + return serverVar; + } + + @JsonPropertyOrder({"description", "default", "enum"}) + public static abstract class ServerVariableMixin { + @JsonAnyGetter + public abstract Map getExtensions(); + } + +} diff --git a/src/main/java/io/openapitools/swagger/config/SwaggerTag.java b/src/main/java/io/openapitools/swagger/config/SwaggerTag.java new file mode 100644 index 0000000..9dd642d --- /dev/null +++ b/src/main/java/io/openapitools/swagger/config/SwaggerTag.java @@ -0,0 +1,49 @@ +package io.openapitools.swagger.config; + +import java.util.Map; + +import org.apache.maven.plugins.annotations.Parameter; + +import io.swagger.v3.oas.models.tags.Tag; + +public class SwaggerTag { + + /** + * REQUIRED. The name of the tag. + */ + @Parameter(required = true) + private String name; + + /** + * A short description for the tag. CommonMark syntax MAY be used for rich text representation. + */ + @Parameter + private String description; + + /** + * Additional external documentation for this tag. + */ + @Parameter + private SwaggerExternalDoc externalDoc; + + @Parameter + private Map extensions; + + public Tag createTagModel(){ + Tag tag = new Tag(); + + tag.setName(name); + tag.setDescription(description); + + if (externalDoc != null) { + tag.setExternalDocs(externalDoc.createExternalDocModel()); + } + + if (extensions != null && !extensions.isEmpty()) { + tag.setExtensions(extensions); + } + + return tag; + } + +} diff --git a/src/test/resources/expectedOutput/full/open-api.json b/src/test/resources/expectedOutput/full/open-api.json index 7d5e40a..e39f3e7 100644 --- a/src/test/resources/expectedOutput/full/open-api.json +++ b/src/test/resources/expectedOutput/full/open-api.json @@ -1 +1 @@ -{"openapi":"3.0.1","info":{"title":"Title","description":"# Description\n\nThis is some description to be included.","termsOfService":"Terms","contact":{"name":"My Name","url":"https://google.com","email":"e@mail.com"},"license":{"name":"MIT","url":"https://license"},"version":"1.0.0","x-custom-property":"My custom property"},"servers":[{"url":"https://services.example.it/base/path","description":"Example URL"}],"paths":{"/accounts":{"get":{"operationId":"list","responses":{"default":{"description":"default response","content":{"application/hal+json":{}}}}}},"/accounts/{regNo}-{accountNo}":{"get":{"description":"Get single account","operationId":"get","parameters":[{"name":"regNo","in":"path","required":true,"schema":{"type":"string"}},{"name":"accountNo","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"404":{"description":"No account found."}}},"put":{"description":"Create new or update existing account","operationId":"createOrUpdate","parameters":[{"name":"regNo","in":"path","required":true,"schema":{"type":"string"}},{"name":"accountNo","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AccountUpdateRepresentation"}}}},"responses":{"404":{"description":"No updating possible"}}}}},"components":{"schemas":{"AccountUpdateRepresentation":{"required":["name"],"type":"object","properties":{"accountNo":{"pattern":"^[0-9]+$","type":"string"},"name":{"pattern":".{1,40}","type":"string"},"regNo":{"pattern":"^[0-9]{4}$","type":"string"}}}}}} +{"openapi":"3.0.1","info":{"title":"Title","description":"# Description\n\nThis is some description to be included.","termsOfService":"Terms","contact":{"name":"My Name","url":"https://google.com","email":"e@mail.com"},"license":{"name":"MIT","url":"https://license"},"version":"1.0.0","x-custom-property":"In Info"},"externalDocs":{"description":"Some external doc at config level","url":"https://example.org","x-custom-property":"In configs's external document"},"servers":[{"url":"https://{sub}.example.it/base/path","description":"Example URL","variables":{"sub":{"description":"The Subdomain","default":"services","enum":["services","web","main"],"x-custom-property":"In ServerVariable"}},"x-custom-property":"In Server"}],"security":[{"first":[]},{"third":["requiredScope1","requiredScope2"]}],"tags":[{"name":"MyTag","description":"MyDescription","externalDocs":{"description":"Some tag's external doc","url":"https://tag.example.org","x-custom-property":"In tag's external document"},"x-custom-property":"In tag"}],"paths":{"/accounts":{"get":{"operationId":"list","responses":{"default":{"description":"default response","content":{"application/hal+json":{}}}}}},"/accounts/{regNo}-{accountNo}":{"get":{"description":"Get single account","operationId":"get","parameters":[{"name":"regNo","in":"path","required":true,"schema":{"type":"string"}},{"name":"accountNo","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"404":{"description":"No account found."}}},"put":{"description":"Create new or update existing account","operationId":"createOrUpdate","parameters":[{"name":"regNo","in":"path","required":true,"schema":{"type":"string"}},{"name":"accountNo","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AccountUpdateRepresentation"}}}},"responses":{"404":{"description":"No updating possible"}}}}},"components":{"schemas":{"AccountUpdateRepresentation":{"required":["name"],"type":"object","properties":{"accountNo":{"pattern":"^[0-9]+$","type":"string"},"name":{"pattern":".{1,40}","type":"string"},"regNo":{"pattern":"^[0-9]{4}$","type":"string"}}}},"securitySchemes":{"first":{"type":"apiKey","description":"Via web gateway","name":"X-API-TOKEN","in":"header"},"fourth":{"type":"openIdConnect","openIdConnectUrl":"https://id.example.org"},"second":{"type":"http","scheme":"MyCredentials","bearerFormat":"password"},"third":{"type":"oauth2","flows":{"implicit":{"authorizationUrl":"https://auth.example.org","refreshUrl":"https://refresh.example.org","scopes":{"x":"y"},"x-custom-property":"In third SecurityScheme's implicit flow"},"password":{"tokenUrl":"https://token.example.org"},"clientCredentials":{"tokenUrl":"https://client.token.example.org"},"authorizationCode":{"authorizationUrl":"https://code.auth.example.org","tokenUrl":"https://code.token.example.org"},"x-custom-property":"In third SecurityScheme's flow"}}}},"x-custom-property":"In Config"} \ No newline at end of file diff --git a/src/test/resources/expectedOutput/full/open-api.yaml b/src/test/resources/expectedOutput/full/open-api.yaml index 2cb5854..0d79cfd 100644 --- a/src/test/resources/expectedOutput/full/open-api.yaml +++ b/src/test/resources/expectedOutput/full/open-api.yaml @@ -14,10 +14,37 @@ info: name: MIT url: https://license version: 1.0.0 - x-custom-property: My custom property + x-custom-property: In Info +externalDocs: + description: Some external doc at config level + url: https://example.org + x-custom-property: In configs's external document servers: -- url: https://services.example.it/base/path +- url: https://{sub}.example.it/base/path description: Example URL + variables: + sub: + description: The Subdomain + default: services + enum: + - services + - web + - main + x-custom-property: In ServerVariable + x-custom-property: In Server +security: +- first: [] +- third: + - requiredScope1 + - requiredScope2 +tags: +- name: MyTag + description: MyDescription + externalDocs: + description: Some tag's external doc + url: https://tag.example.org + x-custom-property: In tag's external document + x-custom-property: In tag paths: /accounts: get: @@ -82,4 +109,35 @@ components: type: string regNo: pattern: ^[0-9]{4}$ - type: string \ No newline at end of file + type: string + securitySchemes: + first: + type: apiKey + description: Via web gateway + name: X-API-TOKEN + in: header + fourth: + type: openIdConnect + openIdConnectUrl: https://id.example.org + second: + type: http + scheme: MyCredentials + bearerFormat: password + third: + type: oauth2 + flows: + implicit: + authorizationUrl: https://auth.example.org + refreshUrl: https://refresh.example.org + scopes: + x: "y" + x-custom-property: In third SecurityScheme's implicit flow + password: + tokenUrl: https://token.example.org + clientCredentials: + tokenUrl: https://client.token.example.org + authorizationCode: + authorizationUrl: https://code.auth.example.org + tokenUrl: https://code.token.example.org + x-custom-property: In third SecurityScheme's flow +x-custom-property: In Config diff --git a/src/test/resources/generate-mojo-full-pom.xml b/src/test/resources/generate-mojo-full-pom.xml index 2e51c7a..a7d0fb0 100644 --- a/src/test/resources/generate-mojo-full-pom.xml +++ b/src/test/resources/generate-mojo-full-pom.xml @@ -16,12 +16,6 @@ swagger-maven-plugin - - - https://services.example.it/base/path - Example URL - - Title 1.0.0 @@ -36,10 +30,132 @@ MIT - My custom property + In Info src/test/resources/descriptions.md + + + https://{sub}.example.it/base/path + Example URL + + + The Subdomain + services + + services + web + main + + + In ServerVariable + + + + + In Server + + + + + + + apikey + Via web gateway + X-API-TOKEN + header + + In first SecurityScheme + + + + http + MyCredentials + password + + + oauth2 + + + https://auth.example.org + https://refresh.example.org + + y + + + In third SecurityScheme's implicit flow + + + + https://token.example.org + + + + https://client.token.example.org + + + + https://code.auth.example.org + https://code.token.example.org + + + + In third SecurityScheme's flow + + + + + openIdConnect + https://id.example.org + + + + + + + + first + + + + + + + third + + requiredScope1 + requiredScope2 + + + + + + + + MyTag + MyDescription + + Some tag's external doc + https://tag.example.org + + In tag's external document + + + + In tag + + + + + Some external doc at config level + https://example.org + + In configs's external document + + + + In Config + io.openapitools.swagger.example