openapitools/empoa

Code (implementation, experiments, tools...) for the Eclipse MicroProfile OpenAPI project

empoa's Issues

Add methods to get the refs from the simple name

Add following methods to obtain the ref value from a simple name:

OASUtil.toRefAPIResponse(String)
OASUtil.toRefCallback(String)
OASUtil.toRefExample(String)
OASUtil.toRefHeader(String)
OASUtil.toRefLink(String)
OASUtil.toRefParameter(String)
OASUtil.toRefRequestBody(String)
OASUtil.toRefSchema(String)
OASUtil.toRefSecurityScheme(String)

Example:

OASUtil.toRefSchema("Foo") will return "#/components/schemas/Foo"

Util: add a utility method to combine parameters

Parameters can be defined at PathItem or Operation level.

A method to combine the parameters between those 2 levels in a null safe way could be added:

List<Parameter> allParameters = new ArrayList<>();
if (pathItem.getParameters() != null) {
    allParameters.addAll(pathItem.getParameters());
}
if (operation.getParameters() != null) {
    allParameters.addAll(operation.getParameters());
}
return allParameters;

The tck test suite should provide the expected JSON as separated file

Currently the expected JSON files are hard coded:

empoa/empoa-extended-tck/src/main/java/org/openapitools/empoa/extended/tck/AbstractElementSerializerTest.java

Lines 331 to 351 in f1a09f8

	assertThatJson(json).isEqualTo(
	"" +
	"{\n" +
	" \"tags\": [\n" +
	" \"Tag\"\n" +
	" ],\n" +
	" \"description\": \"Some description\",\n" +
	" \"parameters\": [\n" +
	" {\n" +
	" \"name\": \"SomeName\",\n" +
	" \"in\": \"query\",\n" +
	" \"description\": \"Some description\",\n" +
	" \"schema\": {\n" +
	" \"title\": \"Title\",\n" +
	" \"type\": \"string\",\n" +
	" \"description\": \"Some description\"\n" +
	" }\n" +
	" }\n" +
	" ]\n" +
	"}"
	);

It would be better to have them as separated JSON files.

GSON Serializer: wrong attribute for additionalProperties

When serialising to JSON with GSON Serializer of following Schemas:

Case 1:

Schema schema = OASFactory.createSchema()
    .type(Schema.SchemaType.OBJECT)
    .title("A title")
    .description("A description")
    .additionalPropertiesBoolean(true);

Case 2:

Schema schema = OASFactory.createSchema()
    .type(Schema.SchemaType.OBJECT)
    .title("A title")
    .description("A description")
    .additionalPropertiesSchema(
        OASFactory.createSchema()
            .type(Schema.SchemaType.INTEGER)
            .format("int32")
            .title("Title")
            .description("Some description")
    );

The JSON output is not correct.

Gson Serializer: "defaultValue" instead of "default"

defaultValue is wrong. It should be: default

server variable:

OASFactory.createServer()
    .url("http://{version}.example-test.com:8080/{username}/")
    .description("Test server")
    .variables(
        createServerVariables()
            .addServerVariable(
                "version", createServerVariable()
                    .addEnumeration("v1")
                    .addEnumeration("v2")
                    .addEnumeration("v3")
                    .defaultValue("v1")
            )
            .addServerVariable(
                "username", createServerVariable()
                    .defaultValue("alice")
                    .description("the developer username")
            )
    )

Is serialized to:

{
  "url": "http://{version}.example-test.com:8080/{username}/",
  "description": "Test server",
  "variables": {
    "version": {
      "enum": [
        "v1",
        "v2",
        "v3"
      ],
      "defaultValue": "v1"
    },
    "username": {
      "defaultValue": "alice",
      "description": "the developer username"
    }
  }
}

Instead of:

{
  "url": "http://{version}.example-test.com:8080/{username}/",
  "description": "Test server",
  "variables": {
    "version": {
      "enum": [
        "v1",
        "v2",
        "v3"
      ],
      "default": "v1"
    },
    "username": {
      "default": "alice",
      "description": "the developer username"
    }
  }
}

schema:

OASFactory.createSchema()
    .defaultValue("EN")
    .addEnumeration("EN")
    .addEnumeration("FR")
    .addEnumeration("DE")
    .addEnumeration("IT")
    .type(Schema.SchemaType.STRING)

Is serialized to:

{
  "type": "string",
  "defaultValue": "EN",
  "enum": [
    "EN",
    "FR",
    "DE",
    "IT"
  ]
}

Instead of:

{
  "type": "string",
  "default": "EN",
  "enum": [
    "EN",
    "FR",
    "DE",
    "IT"
  ]
}

Migrate to JUnit (prepare run of ModelConstructionTest without Arquillian)

The ModelConstructionTest do not requires any Application Server to run. This class of the TCK contains the tests of the TCK that are relevant for this project.

With eclipse/microprofile-open-api#336 the project decided to put back extends Arquillian to ModelConstructionTest. This is not the case for the 2.0-MR1 version which is currently used, but will be for the next version.

As indicated there, one way to run this test without needing a deployment on an App Server (requested by Arquillian) is to use a custom JUnit runner (or a TestFactory with JUnit 5).

Update MicroProfile OpenAPI to version 2.0-RC2

There is a new version of MicroProfile OpenAPI:
https://github.com/eclipse/microprofile-open-api/releases/tag/2.0-RC2

Swagger: Illegal argument when the input specification is malformed

With an input specification like this:

openapi: 3.0.1
info:
    title: Ping Specification
    version: '1.0'
servers:
    -
        url: 'http://localhost:8000/'
paths:
    /ping:
        get:
            operationId: pingGet
            responses:
                '200':
                    content:
                        application/json:
                            schema:
                                type: object
                                properties:
                                    code:
                                        format: int32
                                        type: Integer
                                    message:
                                        type: String
                    description: OK

The type value in the schema is not expected. See the error report in http://editor.swagger.io/

Structural error at paths./ping.get.responses.200.content.application/json.schema.properties.code.type
should be equal to one of the allowed values
allowedValues: array, boolean, integer, number, object, string
Jump to line 21
Structural error at paths./ping.get.responses.200.content.application/json.schema.properties.code.type
should be equal to one of the allowed values
allowedValues: array, boolean, integer, number, object, string
Jump to line 23

The Eclipse-MicroProfile wrapper generated out of the Swagger-Parser object is not working:

Error:

java.lang.IllegalStateException: Unexpected enum value
	at org.openapitools.empoa.swagger.core.internal.models.media.SwSchema.getType(SwSchema.java:434)

Java code to produce the exception:

String content; // The spec as YAML document presented in the first listing

final OpenAPIParser openApiParser = new OpenAPIParser();
final ParseOptions options = new ParseOptions();
final SwaggerParseResult parserResult = openApiParser.readContents(content, null, options);

OpenAPI openAPI = SwAdapter.toOpenAPI(parserResult.getOpenAPI());

SchemaType schemaType = openAPI.getPaths()
            .getPathItem("/ping")
            .getGET()
            .getResponses()
            .getAPIResponse("200")
            .getContent()
            .getMediaType("application/json")
            .getSchema()
            .getType();

Improvements for Jackson serializer

Changes:

• New methods in OpenAPISerializer to serialize only a part of an OpenAPI specification (just a Schema, an APIResponse, …)
• Fixed some NullPointerException
• Ignore sibling values when $ref is defined. Example:

Schema schema = OASElement.createSchema()
    .ref("#/components/schemas/SomeSchema")
    .title("Some title")
    .description("Some description");

Expected serialization:

{
    "$ref": "#/components/schemas/SomeSchema"
}

And not:

{
    "$ref": "#/components/schemas/SomeSchema",
    "title": "Some title",
    "description": "Some description"
}

OASCopy does not copy Schema additionalProperties correctly

When creating a copy of a Schema containing some additionalProperties, then the created copy does not contains the same value. Example:

        Schema original = OASFactory.createSchema();
        original.setAdditionalPropertiesSchema(
            OASFactory.createSchema()
                .type(SchemaType.STRING)
        );
        Schema copy = OASCopy.copy(original);

Change order of attributes in serialized Schema

In the serialized Schema (JSON or YAML) it would be better to start with type and then format, title, description and then all other attributes.

The change does not affect the semantic of the output but makes it more readable for a human.

Improve YAML serialisation with newer Jackson version

As discussed in FasterXML/jackson-dataformats-text#347 newer version of Jackson (2.11.0 or newer) have started to use quotes and backslashes when serializing String values in the OpenAPI specifications.

Example with a long description:

---
openapi: 3.0.1
info:
  title: Ping Specification
  version: "1.0"
servers:
- url: http://localhost:8000/
paths:
  /ping:
    get:
      description: "This is a long description. Lorem ipsum dolor sit amet, consectetur\
        \ adipiscing elit. Donec dignissim, velit in egestas consectetur, metus dui\
        \ dignissim ipsum, et lacinia tellus purus vitae tortor."
      operationId: pingGet
      responses:
        "200":
          description: OK

The goal is to make the produced YAML conform with the spec:
https://yaml.org/spec/1.2/spec.html#id2788859.

---

With this issue long String values (such as description) will be serialized to a single line:

---
openapi: 3.0.1
info:
  title: Ping Specification
  version: "1.0"
servers:
- url: http://localhost:8000/
paths:
  /ping:
    get:
      description: "This is a long description. Lorem ipsum dolor sit amet, consectetur adipiscing elit. Donec dignissim, velit in egestas consectetur, metus dui dignissim ipsum, et lacinia tellus purus vitae tortor."
      operationId: pingGet
      responses:
        "200":
          description: OK

NullPointerException with gson serializer

With following elements, the gson serializer produces a NullPointerException when the map is null:

• Paths
• Callback
• Content
• APIResponses
• Scopes
• SecurityRequirement
• ServerVariables

Packaging should be jar in the published artifacts

The published artifacts have the packaging defined as pom.

Example taken from empoa-swagger-core-1.0.0.pom:

<project xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
  <modelVersion>4.0.0</modelVersion>
  <groupId>org.openapitools.empoa</groupId>
  <artifactId>empoa-swagger-core</artifactId>
  <version>1.0.0</version>
  <packaging>pom</packaging>
  <name>EMPOA Swagger-Core</name>
...

It should be jar.