Delightful code generation for OpenAPI specs for Swift written in Swift
Create API
Delightful code generation for OpenAPI specs for Swift written in Swift.
- Fast: processes specs with 100K lines of YAML in less than a second
- Smart: generates Swift code that looks like it’s written by hand
- Reliable: tested on 500K lines of publically available OpenAPI specs producing correct code every time
- Customizable: offers a ton of customization options
Powered by OpenAPIKit
Status: pre-release
Arguments
ARGUMENTS:
<input> The OpenAPI spec input file in either JSON or YAML format
OPTIONS:
--output <output> The output folder (default: ./.create-api/)
--config <config> The path to configuration. If not present, the command will look
for .createAPI file in the current folder. (default: /.create-api.yml)
-s, --split Split output into separate files
-v, --verbose Print additional logging information
--strict Throws an error if it fails to generate any of the constructs from
the input spec
--watch Monitor changes to both the spec and the configuration file and
automatically re-generated input
--package <package> Generates a complete package with a given name
--module <module> Use the following name as a module name
--vendor <vendor> Enabled vendor-specific logic (supported values: "github")
--generate <generate> Specifies what to generate (default: paths, entities)
--filename-template <filename-template>
Example: "%0.generated.swift" will produce files with the following names:
"Paths.generated.swift". (default: %0.swift)
--single-threaded By default, saturates all available threads. Pass this option
to turn all parallelization off.
--measure Measure performance of individual operations
-h, --help Show help information.
Configuration
CreateAPI supports a massive number of customization options with more to come. You can use either YAML or JSON as configuration files.
An example configuration file featuring all available options set to the default parameters.
# Modifier for all generated declarations
access: public
# Add @available(*, deprecated) attributed
isAddingDeprecations: true
# Generate enums for strings
isGeneratingEnums: true
# Example: "enabled" -> "isEnabled"
isGeneratingSwiftyBooleanPropertyNames: true
# Any schema that can be conveted to a type identifier.
# Example: "typealias Pets = [Pet], is inlined as "[Pet]".
isInliningTypealiases: true
# Example: "var sourcelUrl" becomes "var sourceURL"
isReplacingCommonAcronyms: true
# Acronyms to add to the default list
addedAcronyms: []
# Acronyms to remove from the default list
ignoredAcronyms: []
# Example: "var file: [File]" becomes "var files: [File]"
isPluralizationEnabled: true
# Available values: ["spaces", "tabs"]
indentation: spaces
# By default, 4
spaceWidth: 4
# Parses dates (e.g. "2021-09-29") using `NaiveDate` (https://github.com/kean/NaiveDate)
isNaiveDateEnabled: true
# If enabled, uses `Int64` or `Int32` when specified.
isUsingIntegersWithPredefinedCapacity: false
# Disableds SwiftLint
isSwiftLintDisabled: true
# Overrides file
fileHeader: null
entities:
# Skipped entities, e.g. ["SimpleUser"]
skip: []
# Generates entities as structs
isGeneratingStructs: true
# Generate the following entities as classes
entitiesGeneratedAsClasses: []
# Generate the following entities as structs
entitiesGeneratedAsClasses: []
# Makes classes final
isMakingClassesFinal: true
# Base class for entities generated as classes
baseClass: null
# Protocols adopted by entities
protocols: ["Codable"]
# Generate initializers for all entities
isGeneratingInitializers: true
# If disabled, will use strings as coding keys
isGeneratingCustomCodingKeys: true
# By default, the order matches the order in the spec
isSortingPropertiesAlphabetically: false
# Add defaults values for booleans and other types when specified
isAddingDefaultValues: true
# For `allOf` inline properties from references
isInliningPropertiesFromReferencedSchemas: false
# Changes how unspecified additional properties are interpreted
isAdditionalPropertiesOnByDefault: true
paths:
# Skipped paths, e.g. ["/gists/{gist_id}/commits"]
skip: []
# Available options:
# - "rest" - generate structs to represent path components
# - "operations" - generate a plain list of operatinos
style: rest
# Namespace for all generated paths
namespace: "Paths"
# Generate response headers using https://github.com/kean/HTTPHeaders
isGeneratingResponseHeaders: true
# Add operation id to each request
isAddingOperationIds: false
# The types to import, by default uses "Get" (https://github.com/kean/Get)
imports: ["Get"]
# Example, "- empty: Void"
overrideResponses: {}
# Overrides the query parameter encoders, example:
# - Date: "ISO8601DateFormatter().string(from: self)"
queryParameterEncoders: null
# Inline simple requests, like the ones with a single parameter
isInliningSimpleRequests: true
# Inline simple parametesr with few arguments.
isInliningSimpleQueryParameters: true
# Threshold from which to start inlining query parameters
simpleQueryParametersThreshold: 2
# Tries to remove redundant paths
isRemovingRedundantPaths: true
rename:
# Rename properties, example:
# - name: firstName
# - SimpleUser.name: firstName
properties: {}
# Rename query parameters
parameters: {}
# Rename enum cases
enumCases: {}
# Rename entities
entities: {}
# Rename operation when "paths.style: operations" is used
operations: {}
# Rename anynomous collection elements. By default, use
# a singularized form of the property name
collectionElements: {}
comments:
# Generate comments
isEnabled: true
# Generate titles
isAddingTitles: true
# Generate description
isAddingDescription: true
# Generate examples
isAddingExamples: true
# Add links to the external documenatation
isAddingExternalDocumentation: true
# Auto-capitalizes comments
isCapitalizationEnabled: true
Adding Specs
If you are using CreateAPI and want your spec to be part of the regression testing – open a PR adding it to GenerateTests
test suite and provide your configuration.
OpenAPI Support
The following features are not suppored (yet):
- External References
allowReserved
andallowEmptyValue
option in query parametersspaceDelimited
,pipeDelimited
, anddeepObject
query parametersstyle
values, form encoding only supports primitive types
Upcoming:
- An improved way to generate patch parameters. Support for JSON Patch.
- OpenAPI 3.1 support.