/dart-openapi-maven

A Maven dependency for use with the OpenAPI swagger Maven plugin

Primary LanguageHTMLBSD 2-Clause "Simplified" LicenseBSD-2-Clause

Opinionated Dart OpenAPI v3 Plugin

This plugin is designed for use by the OpenAPi v3 Maven Plugin and generates Dart code. It differs from the one built in because it does not generate a few files which I don’t think should be generated (as they will get overwritten each time - such as .gitignore, travis.yml, etc), and behaves in a weird way with some things (such as enums) which I didn’t agree with.

It also significantly splits out all of the client api code into Browser and CLI versions so that it can be used with Flutter for Web, or plain Dart/Flutter Mobile (using Dart IO) without having to generate two completely different projects.

It also cleans up a bunch of code around streamed data handling.

This is likely to go through a few more versions as it is used comprehensively.

There is an article on Medium discussing this plugin.

Developers

Changelog

  • 3.1 - introduces support for the Kubernetes API in terms of compilation along with a considerable degree of support for the complexity of that API. It also reduces the code generated when no forms are used or forms are used but not json. It also supports the return of non-json data by just returning the string, allowing you to decode it.

  • 2.9 - support inheritance using allOf where it exists. If the model from the generator provides a parentClass we modify the output to now support the correct code generation to support inheritance. Resolve issue around headers not being merged if passed by user. Fix issue with form data generation where fields need to be json encoded.

  • 2.8 - resolves a number of Dart Analysis issues

  • 2.6/7 - add in a new copyWith() method that allows you to make deep copies of the model and replace specific parts

  • 2.5 - fixed a dangling } issue from pedantic, fixed additionalProperties support for k8s api generation, added integration tests

  • 2.4 - fixed an issue if no authNames were being provided, a List<dynamic> was created instead of a List<String>

  • 2.3 - this is a cleanup of the move to Dio based on pedantic feedback

  • 1.5 - fixed the pubspec.yaml

  • 1.4 - added in serialization of outgoing data because Dart cannot serialize an enum using json.

Roadmap

  • We intend to support the oneOf syntax for parameters for request and response types by using optional parameters. This won’t change method calls when you are only passing one type.

  • We will start investigating how to support anyOf syntax.

  • We intend to be generating server side code for supporting Dart server side applications.

Usage

To use it, do something like this:

      <plugin>
        <groupId>org.openapitools</groupId>
        <artifactId>openapi-generator-maven-plugin</artifactId>
        <version>4.3.0</version>
        <dependencies>
          <dependency>
            <groupId>com.bluetrainsoftware.maven</groupId>
            <artifactId>openapi-dart-generator</artifactId>
            <version>3.1</version>
          </dependency>
        </dependencies>
        <executions>
          <execution>
            <id>mr-api</id>
            <goals>
              <goal>generate</goal>
            </goals>
            <phase>generate-sources</phase>
            <configuration>
              <output>${project.basedir}</output>
              <inputSpec>${project.basedir}/target/mrapi/mr-api.yaml</inputSpec>
              <generatorName>dart2-api</generatorName>
              <enablePostProcessFile>true</enablePostProcessFile>
            </configuration>
          </execution>
        </executions>
      </plugin>

We use the enablePostProcessFile because if it finds a FLUTTER environment variable, it will run dartfmt on the generated files.

We typically use the Dependency Plugin to copy the actual OpenAPI yaml file from a different project - such as in this case "mr-api".

      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-dependency-plugin</artifactId>
        <executions>
          <execution>
            <id>unpack todo api</id>
            <phase>initialize</phase>
            <goals>
              <goal>unpack</goal>
            </goals>
            <configuration>
              <artifactItems>
                <artifactItem>
                  <groupId>io.yourapi.mr</groupId>
                  <artifactId>mr-api</artifactId>
                  <version>1.1-SNAPSHOT</version>
                  <type>jar</type>
                  <outputDirectory>${project.basedir}/target/mrapi/</outputDirectory>
                </artifactItem>
              </artifactItems>
              <includes>
                **/*.yaml
              </includes>
              <overWriteReleases>true</overWriteReleases>
              <overWriteSnapshots>true</overWriteSnapshots>
            </configuration>
          </execution>
        </executions>
      </plugin>

And we include a custom Clean plugin definition to ensure old artifacts aren’t left behind as you generate.

      <plugin>
        <artifactId>maven-clean-plugin</artifactId>
        <version>3.1.0</version>
        <configuration>
          <filesets>
            <fileset>
              <directory>lib</directory>
              <includes>
                <include>**/**</include>
              </includes>
            </fileset>
            <fileset>
              <directory>docs</directory>
              <includes>
                <include>**/**</include>
              </includes>
            </fileset>
            <fileset>
              <directory>test</directory>
              <includes>
                <include>**/**</include>
              </includes>
            </fileset>
            <fileset>
              <directory>.openapi-generator</directory>
              <includes>
                <include>**/**</include>
              </includes>
            </fileset>
            <fileset>
              <directory>.openapi-generator</directory>
              <includes>
                <include>**/**</include>
              </includes>
            </fileset>
          </filesets>
        </configuration>
      </plugin>