wolfadex/elm-open-api-cli

A CLI tool for generating Elm modules from Open API specs.

Elm API SDK Generator

Generate an Elm SDK from an OpenAPI Spec (OAS).

Goal

To allow developers to generate an Elm module(s) from an OpenAPI Spec. This is primarily for developers wanting to integrate with a 3rd party service that doesn't provide an Elm SDK for their service. It can also be used within a company where the back end generates an OAS from the written code or an OAS is written and used to generate both the backend and Elm SDKs.

Example Usage

A RealWorld app using a generated SDK to demonstrate how to use it.

Using the CLI

Contributing to Development

Thank you

• miniBill for your many contributions
• elm-pages for making it easy to write a CLI app in Elm
• Elm for an easy to use & maintain language

elm-open-api-cli's Issues

Schema gets weird \" escapes from Yaml parsing

I have no idea why this happens on my schema and not on the github-spec.json. But it is consistent:

{
  "components": {
    "responses": {},
    "schemas": {}
  },
  "info": {
    "title": "Sample",
    "version": "0.1"
  },
  "openapi": "3.0.0",
  "paths": {},
  "security": [],
  "servers": [],
  "tags": []
}

Removing the option for yaml and forcing a simple Json.decode works great.

Running the code as is gives this:

-- CUSTOM ERROR --------------- 
Problem with the value at json.openapi:

    "\"3.0.0\""

Invalid version format

Some definitions fail to generate correctly in generated output

When generating the SpaceTraders API from their spec, the generated output is invalid. For example some types have no definitions.

Command:

elm-open-api \"https://stoplight.io/api/v1/projects/spacetraders/spacetraders/nodes/reference/SpaceTraders.json?fromExportButton=true&snapshotType=http_service&deref=optimizedBundle\" --output-dir src --module-name \"Generated.SpacetradersApi\" --generateTodos true

Example of the issue:

Also there are cases such as type alias ActivityLevel = String but this type should be limited to the 4 valid values WEAK, GROWING, STRONG, RESTRICTED as documented in the spec. - Striked out as this is an issue with their own types in the spec.

Notes:

No errors are thrown during generation but warnings about Warning: Error! Multiple security requirements but this is expected? I suppose this is something being worked on still, or what's the plan for security topics?

Add risky variants to generated tasks and requests

Thank you for creating this package!

Maybe I missed it somewhere. But is there a way to get risky variants of tasks/requests generated?

Moved from wolfadex/elm-open-api#5

cc @myrho

Better handling of non-2XX responses

Currently we only return the status code, but we should return the body as well.

Required field in Spotify OAS generates as `Maybe`

See discussion on Discourse https://discord.com/channels/534524278847045633/1127980433263566889/1158093368291770368

Cmd requests don't always get a generate type definition

Tasks do but Cmds are sometimes missing the type definition

Support custom properties, i.e. `x-*`

This will require some design work as these can be nearly any value.

• How do we let users hook into the CLI?
• How do we let users generate code in a safe/compatible way?

Support for Swagger, aka < v3.0 OAS

Link to https://converter.swagger.io/ for anyone looking to use Swagger, aka before v3.0, OAS. This should also be linked to in https://github.com/wolfadex/elm-open-api

API Specs with custom response media types from vendors as defined in RFC6838 don't work

Response media types such as application/vnd.github.v3+json, or in my case application/vnd.amadeus+json, should be parsed as valid JSON APIs but in my case I get:

Error! Could not get application's application/json content
Path: airlines

As described in section 3.2 or RFC6838, vnd additions are simply vendor registrations, followed by a possible version and then the response format therein.

Not sure how easy this is to fix and deploy but it is a common enough thing that it would be worth having included in the parser and validator for content type resolution and elsewhere this is used, read or verified, etc.

Errors with `--output` and `--namespace`

• Using the argument --output=src-generated/Api.elm creates ./src-generated/Api.elm but has the default module name.
• Using the argument --namespace=src-generated/Api.elm creates ./generates/src-generated/Api.elm with the module name Api.elm
• Using both arguments results in the correct file name & location, but a module name of src-generated/Api.elm

Support for lenient decoding

I don't know if anyone else has a use for this, but I am working with an internal Open API spec that apparently is not completely valid according to the spec. Out of hundreds of endpoints, there were a handful with empty responses objects (so the JSON would contain literally "responses":{}). I didn't really care about the offending endpoints, so in order to keep just the good ones, I ended up vendoring this project and the elm-open-api project with a modified decoder for "paths" that just filters out the malformed endpoints.
https://github.com/pete-murphy/elm-open-api-cli/blob/95e76eec0399f573037450d6beecd0b958664b1e/src/OpenApi.elm#L111-L126
I figured I'd share in case anyone else has a similar issue, though I don't have any idea about how the API for this tool could have been extended to support my use case, or if anyone would even want that.

Docs are confusting when it comees to usage vs working on

The section Getting Started is for using this tool while the section Development is for working on it. This has caused confusion. The contributing section should be moved to a separate file and linked to.

See wolfadex/elm-open-api#4 for additional notes.

Better UX when failing to decode OAS

Incorrect comand in docs

The README currently say to run

node elm-open-api ./page/to/oas.json

but it should say

npx elm-open-api ./page/to/oas.json

See wolfadex/elm-open-api#4 for additional notes.

Use path segments parameter for Url.crossOrigin

It'd be great if the urls could be generated using Url.crossOrigin's path segments parameter. In my case, an openapi endpoint /example/{x} results in this Elm code

            Url.Builder.crossOrigin
                (String.replace
                    "{x}"
                    config.params.x
                    "http://example.com/example/{x}"
                )
                []
                ...

which then results in an url with a trailing slash http://example.com/example/x/. However, this then does not match the endpoint's url in the openapi spec which is without trailing slash.

Would it be possible to have the Elm code being generated like this:

            Url.Builder.crossOrigin
                "http://example.com"
                [ "example"
                , config.params.x
                ]
                ...

Then the resulting url would be without trailing slash and hence matching the openapi spec.

Moved from wolfadex/elm-open-api#6

cc @myrho

Name collision with the custom error name of `Error`

The Amadeus OAS (as seen in the example/ directory) has an error response named error which collides with the custom type this tool generates.

Moving the helper code like the custom error type, the resolveWhatever, and related code to their own module separate from the Api module will resolve this.

Value validation handling improvements

I also see that cases such as Agent and their related validations are not correctly generated also, for example lengths or ranges don't seem to be tested, only that the field exists.

Originally posted by @jamesrweb in #65 (comment)

Typos in the readme

Currently says: [--moduel-name <moudle name>]
Should say: [--module-name <module name>]

Improve module name generation

Hi, thank you for this awesome tool! It is going to be super helpful for me!

I ran into an issue with a module name being generated that was not "Elm compliant". If a service provider includes an OAS file with a strangely formatted title such as the one below the module and filename generated are invalid. Possibly, add additional sanitization to ensure that the module and filename have valid names.

{
  "info": {
    "title": "service API (params in:body)",
}  

I guess this might become Service_API__Params_In_Body_.elm?

Thanks!

Vendor the necessary parts of elm-community/json-extra

Vendor the necessary parts of elm-community/json-extra so that it's no longer a dependency.

The Elm Yaml parser has a bug with being unable to parse multiline strings

• Maybe switch to MaybeJustJames/yaml as it's been more recently updated?
• Maybe fork and fix it ourselves

Response names (types) sometimes start with numbers (status codes)

Some of the Amadeus OAS have response names of the form 400_Search. This isn't a valid name and needs to be Elm-ified.

File upload with additional parameters not supported

I have an OpenAPI spec with the following request:

"/api/files": {
      "post": {
        "tags": [
          "files"
        ],
        "summary": "Create File",
        "operationId": "create_file_api_files_post",
        "requestBody": {
          "content": {
            "multipart/form-data": {
              "schema": {
                "$ref": "#/components/schemas/Body_create_file_api_files_post"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "Successful Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/JsonCreateFileOutput"
                }
              }
            }
          },
          "422": {
            "description": "Validation Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            }
          }
        }
      }

Where the body is defined as:

"Body_create_file_api_files_post": {
        "properties": {
          "file": {
            "type": "string",
            "format": "binary",
            "title": "File"
          },
          "description": {
            "type": "string",
            "title": "Description"
          }
        },
        "type": "object",
        "required": [
          "file",
          "description"
        ],
        "title": "Body_create_file_api_files_post"
      }

When I give that to elm-open-api it produces:

-- config.body is "{ body : Bytes.Bytes }"
createFileApiFilesPost config =
    Http.request
        { method = "POST"
        , headers = []
        , expect = Http.expectJson config.toMsg decodeJsonCreateFileOutput
        , body = Http.bytesBody "multipart/form-data" config.body
        , timeout = Nothing
        , tracker = Nothing
        , url = "/api/files"
        }