Evaluate OpenAPI tooling

[pvdbosch]

In GitLab by @pvdbosch on Sep 7, 2018, 16:25

1. Test senya.io, stoplight.io, apicurio or any other interesting tool to author swagger files.

2. Evaluate code generation maven plugins: openapi-generator vs swagger codegen.
   Recommend one?

Comparison (WIP):

Swagger codegen:

• specifying explicitely additionalProperties: true was required to let generated Java classes support additional properties not specified in the Swagger file (untested on openapi-generator)
  • even with this specified, the generated code didn't work properly
• when generating fat swagger, creates top level types for inlined (non-Venetian-blind) types. It shouldn't. The generated types don't follow styleguide naming convention. (untested on openapi-generator)
• generated code's formatting a bit better
• invalid escaping for regexp: @Pattern(regexp="\d{11}") => doesn't compile, should be @Pattern(regexp="\\d{11}") (tested with v3 of codegen)

openapi-generator:

• more actively developed
• unnecessary java imports, bad formatting in generated code - maybe fixable with some tuning
• additionalProperties: true has no effect
• 4.x use of allOf:
  • generate useless *AllOf classes for Swagger types inlined in an allOf composition. They are imported in the composite class but not used
  • no inheritance in generated code anymore when using allOf with a referenced type: e.g. InvalidParamProblem no longer extends Problem (see [BUG] [Java] inheritance is generated without discriminator field OpenAPITools/openapi-generator#5097 (comment))
  • workaround for both: only specify base class in allOf and specify properties on same level like this:
    MyType: { allOf: [$ref: '#/components/schemas/T'], properties: { x: {type: string}} }
• converts format: uri to java.net.URI as of 4.1.0
• In 4.3.1: inline object types become java.lang.Object instead of proper generated type. Workaround: make them explicit (non-inline) types

Other notes:

• specifying an array of types, while valid JSON Schema, doesn't seem to be supported in OpenAPI
• format: decimal isn't part of the OpenAPI standards, and isn't supported for code generation
• Custom typemappings may be needed in maven config, e.g.
  • to get byte array as return type (e.g. when returning image) for type: file instead of default java.io.File:
    <typeMappings><typeMapping>file=byte[]</typeMapping></typeMappings>
• all plugins: JAX-RS always returns a default http status code (200 for OK with body, 204 for OK without body). Only way to override is by generating javax.ws.rs.core.Response return types for all generated models.

3. Smals will share their extensions to the code generation plugin, adding proper support for additional properties to all generated classes.

[pvdbosch]

In GitLab by @pvdbosch on Oct 5, 2018, 12:01

Most authoring tools seem to have difficulties with definitions referenced from external YAML files.

Some feedback from our developers:

• senya.io: IntelliJ plugin.
  • Problems with external schemas in graphical view, though supported in text view (i.e. links can be followed)
  • marks some properties as faulty while they're valid OpenAPI 2.0: the 'examples' property in a Response Object, and a property defined without a type
• swagger editor: also problems with external references; (see this issue and this other issue.
• might be working if files are reachable by http instead file:///
• Only tested with v3. Issue mentions swagger editor v2 might support it better than v3.
• Stoplight is not free of charge, so didn't test
• apicur.io: only single file swagger. No switching between graphical and text representation. Still beta.

RepreZen is another paying alternative, but didn't try out yet.

[pvdbosch]

In GitLab by @pvdbosch on Nov 23, 2018, 16:21

Latest 0.20 version of Senya works fine now. Tested with socialStatus API, with external files, both in text as UI mode.

I reported the bug concerning examples (as mentioned in #28) in Swagger and it got fixed.
Senya follows closely the OpenAPI 2.0 spec, which means that you have to use the MIME type as key of each example, matching one of the 'produces' MIME types. This means you can only specify a single example per response status code. For the socialStatuses API, we used to specify multiple examples using some free text description as key, as the Swagger editor didn't verify that they were MIME types.
The OpenAPI 3.0 spec does allow specifying multiple examples.

[pvdbosch]

In GitLab by @pvdbosch on Dec 17, 2018, 11:54

KaiZen as eclipse plugin

SwaggerUI watcher https://github.com/moon0326/swagger-ui-watcher views in browser

can be added to list of tools in style guide

[pvdbosch]

In GitLab by @wsalembi on Jan 20, 2019, 12:09

Senya Editor for Intellij IDEA has become a paid plugin for https://senya.io/release-notes-1-0-0/ (48 euro/year)

[pvdbosch]

In GitLab by @pvdbosch on Jan 22, 2019, 10:15

updated the styleguide:

• split tools and references section, add some more description
• mention Senya is commercial
• add Zalando's IntelliJ plugin

[pvdbosch]

In GitLab by @pvdbosch on Jan 22, 2019, 11:53

changed title from evaluate {-tools to author swagger files-} to evaluate {+swagger tooling+}

[pvdbosch]

In GitLab by @pvdbosch on Jan 22, 2019, 12:11

Broadening scope of the issue to also include other tooling, like codegen.

For code generation from swagger, there are two plugins:

• swagger-codegen: https://github.com/swagger-api/swagger-codegen
• openapi-generator from OpenAPITools: https://github.com/OpenAPITools/openapi-generator (= fork of swagger-codegen)

Both still seem under active development, though openapi-generator seems to have more activity.
What are practical experiences with the plugins of the WG members? Do we recommend the openapi-generator one?

Some issues encountered by @VirginieHayot when using the swagger codegen:

• specifying explicitely additionalProperties: true was required to let generated Java classes support additional properties not specified in the Swagger file
• even with this specified, the generated code didn't work properly

Smals (@smals-wisa ) developed an extension to the plugin, adding proper support for additional properties to all generated classes. It would be interesting to other WG members if this extension could be shared.

[pvdbosch]

In GitLab by @pvdbosch on Feb 26, 2019, 13:50

Added WIP comparison between codegen plugin to issue description, everyone can contribute.

[pvdbosch]

In GitLab by @pvdbosch on Feb 26, 2019, 13:50

changed the description

[pvdbosch]

In GitLab by @pvdbosch on Feb 27, 2019, 12:14

changed the description

[pvdbosch]

In GitLab by @pvdbosch on Feb 27, 2019, 12:17

Another codegen issue encountered with InvalidParamProblem; arrays of types cause property to be ignored during code generation:

  InvalidParam:
    type: object
    properties:
      in:
        type: string
      name:
        type: string
      reason:
        type: string
      value:
        # allow all types, as type is mandatory. Known issue: property is ignored when using swagger codegen (see #25)
        type: [string, number, integer, boolean, array, object, 'null']

(from new problem-v1.yaml)

[pvdbosch]

In GitLab by @pvdbosch on Feb 27, 2019, 12:47

mentioned in commit 229c7e7

[pvdbosch]

In GitLab by @pvdbosch on Mar 11, 2019, 09:50

Omitting type on the value property; this works with code generation to get Object type.

Having no type is valid OpenAPI 2.0 even though KaiZen (and maybe some other editors) indicates it as an error.