Swiftpack.co - Package - yonaskolb/SwagGen


Platforms SPM Git Version Build Status license

SwagGen is a command line tool that generates client code from a Swagger/OpenAPI 2.0 Spec.

It is an alternative the official swagger-codegen java code generator, and adds some improvements such as speed, configurability, simplicity, extensibility, an improved templating language, and a great Swift template.

The default Swift templates it generates include support for model inheritance, shared enums, mutable parameter structs, convenience initialisers, inline schemas, Codable and Equatable models, configurable model options, generic networking stack, decoding options, and many other niceties.


Make sure Xcode 9.3 is installed first.


$ mint install yonaskolb/SwagGen


$ brew tap yonaskolb/SwagGen https://github.com/yonaskolb/SwagGen.git
$ brew install SwagGen


$ git clone https://github.com/yonaskolb/SwagGen.git
$ cd SwagGen
$ make install

Swift Package Manager

Use as CLI

$ git clone https://github.com/yonaskolb/SwagGen.git
$ cd swaggen
$ swift run

Use as dependency

Add the following to your Package.swift file's dependencies:

.package(url: "https://github.com/yonaskolb/SwagGen.git", from: "1.1.0"),

And then import wherever needed:

import SwagGenKit


Use --help to see usage information

swaggen --help
Usage: swaggen <command> [options]

  generate        Generates a template from a Swagger spec
  help            Prints this help information
  version         Prints the current version of this app


swaggen generate path_to_spec

Use swaggen generate --help to see the list of generation options.

  • spec: This is the path to the Swagger spec and is a required parameter. It can either be a file path or a web url to a YAML or JSON file

  • --language: The language to generate a template for. This defaults to swift for now.

  • --template:: This is the path to the template config yaml file. It can either be a direct path to the file, or a path to the parent directory which will by default look for /template.yml. If this is not passed, the default template for the language will be used.

  • --destination: The directory that the generated files will be added to.

  • --option: An option that will be merged with the template config options with those in this argument taking precedence, meaning any existing options of the same name will be overwritten. This argument can be repeated to pass in multiple options. Options must specify the option name and option value seperated by a colon, with any spaces contained in quotes. The following formats are allowed:

    • -- option myOption:myValue
    • -- option "myOption: my value"
    • -- option myOption:" my value"
  • --clean: Controls if and how the destination directory is cleaned of non generated files. Options are:

    • none: no files are removed (default)
    • all: all other files are removed
    • leave.files: all files and directories except those that start with . in the destination directory are removed. This is useful for keeping configuration files and directories such as .git around, while still making sure that items removed from the spec are removed from the generated API.
  • --verbose: Show more verbose output

  • --silent: Silences any standard output. Errors will still be shown


swaggen generate http://myapi.com/spec --template Templates/Swift  --destination generated --option name:MyAPI --option "customProperty: custom value --clean leave.files"

For the Swift template, a handy option is name, which changes the name of the generated framework from the default of API. This can be set in the template or by passing in --option name:MyCoolAPI.

Swift Template

List of all available options:

name | action | expected values | default value --- | --- | --- | --- name | name of the API | String | API authors | authors in podspec | String | Yonas Kolb baseURL | baseURL in APIClient | String | first scheme, host, and base path of spec fixedWidthIntegers | whether to use types like Int32 and Int64 | Bool | false homepage | homepage in podspec | String | https://github.com/yonaskolb/SwagGen modelPrefix | model by adding a prefix and model file name | String | null modelSuffix | model by adding a suffix and model file name | String | null mutableModels | whether model properties are mutable | Bool | true modelType | whether each model is a struct or class | String | class modelInheritance | whether models use inheritance. Must be false for structs | Bool | true modelNames | override model names | [String: String] | [:] modelProtocol | customize protocol name that all models conform to | String | APIModel enumNames | override enum names | [String: String] | [:] safeArrayDecoding | filter out invalid items in array instead of throwing | Bool | false safeOptionalDecoding | set invalid optionals to nil instead of throwing | Bool | false tagPrefix | prefix for all tags | String | null tagSuffix | suffix for all tags | String | null

If writing your own Swift template there are a few types that are generated that you will need to provide typealias's for:

  • ID: The UUID format. Usually UUID or String
  • File: The file format. Usually URL, Data or a custom type with a mimeType and fileName
  • DateTime: The date-time format. Usually Date
  • DateDay: The date format. Usually Date or a custom type.


$ git clone https://github.com/yonaskolb/SwagGen.git
$ cd SwagGen
$ swift package generate-xcodeproj

This use Swift Project Manager to create an xcodeproj file that you can open, edit and run in Xcode, which makes editing any code easier.

If you want to pass any required arguments when running in XCode, you can edit the scheme to include launch arguments.


Templates are made up of a template config file, a bunch of Stencil files, and other files that will be copied over during generation

Template config

This is the configuration and manifest file for the template in YAML or JSON format. It can contain:

  • formatter: Optional formatter to use. This affects what properties are available in the templates and how they are formatted e.g. Swift
  • templateFiles: a list of template files. These can each have their paths, contents and destination directories modified through Stencil tags. One template file can also output to multiple files if they path is changed depending on a list context. Each file contains:
    • path: relative path to the template config. The extension is usually .stencil or the type it is going to end up as
    • context: optional context within the spec. This is provided to the generated file, otherwise the full context will be passed. If this is a list then a file will be created for each object and the context within that list is used. (e.g. a file for every model in the spec definitions gets it's own definition context). Note that properties in the template options field can be used here
    • destination: optional destination path. This can contain stencil tags whose context is that from the context above. e.g. if context was definitions then the path could be Models/{{ type }}.swift and the filename would be the type of the definition. If this is left out the destination will be the same as the path, relative to the final destination directory. If it resolves to an empty string it will be skipped and not generated.
  • copiedFiles: this is an array of relative paths that will be copied to the destination. They can be files or directories. This is used for files that won't have their contents, filenames or paths changed.
  • options: these are the options passed into every stencil file and can be used to customize the template. These options are merged with the options argument, with the argument options taking precendance. These options can be references in template file paths and their contents.

An example template for Swift can be found here

Template Files

These files follow the Stencil file format outlined here https://stencil.fuller.li


Formatters change what information is available to the templates and how it's formatted. They can be specified via the formatter property in the template config. Usually these would map to a specific target language, but can be customized for different purposes.

Output Languages

SwagGen can be used to generate code for any language. At the moment there is only a formatter and template for Swift

Swift API usage

Usage documentation can be found in the Readme that is generated with your template.


This tool is powered by:

Thanks also to Logan Shire and his work on Swagger Parser


Pull requests and issues are welcome


SwagGen is licensed under the MIT license. See LICENSE for more info.


Stars: 149
Help us keep the lights on

Used By



3.0.1 - Aug 25, 2018


  • Added new modelProtocol template option which defaults to APIModel #109


  • Fixed crash in Swift template when not using any RequestBehaviours #108


3.0.0 - Aug 24, 2018


  • Added File upload support #103
  • Added top level security support #104
  • Added modelType option to Swift template for class or struct models #94
  • Added modelInheritance template option #94
  • Added modelNames and enumNames template options for overriding names #95
  • Added x-enum-name property to Swagger for custom enum names #98
  • Added operation summary to generation and template


  • Swift template changes #104
    • Renamed APIError to APIClientError
    • Removed APIClient.authorizer
    • Added RequestBehavour.validate (replaces APIClient.authorizer)
    • APIClient.makeRequest now returns a CancellableRequest instead of Alamofire.Request
    • A new APIClient.jsonDecoder property which is used for json requests
    • Renamed queue to completionQueue in APIClient.makeRequest
    • Replaced APIError. authorizationError with APIClientError. validationError
    • Rename APIService.authorization to APIService.securityRequirement
  • Generated type changes in Swift template. You will now have to handle or typealias the following types #104
    • ID: The UUID format. Usually UUID or String
    • File: The file format. Usually URL, Data or a custom type with a mimeType and fileName


  • Sort operations in generated Readme
  • Better name camel casing #100
  • Fix empty string field decoding in YAML #101
  • Escape Protocol in swift templates

2.1.2 - Jun 24, 2018


  • Added generated Swift template documenation #87


  • Fixed nil AnyCodable values being encoded as null
  • Fixed inbuilt templates not being found in Mint installations

2.1.1 - Jun 1, 2018


  • Added support for ASCI encoded swagger specs #80


  • Fixed homebrew installation on machines with both Xcode 9.3 and Command line tools installed
  • Fixed UUID parameter encoding #81

2.1.0 - May 17, 2018


  • Separated date and date-time formats into DateDay and DateTime structs #74 #77
  • Added new modelPrefix and modelSuffix options #75


  • Fixed regression where request bodies were not being encoding properly #76
  • Fixed safeOptionalDecoding not working on optional Arrays
  • Fixed date-time not decoding in some cases #77