Swiftpack.co - CreateAPI/CreateAPI as Swift Package

Swiftpack.co is a collection of thousands of indexed Swift packages. Search packages.
See all packages published by CreateAPI.
CreateAPI/CreateAPI 0.1.0
Delightful code generator for OpenAPI specs
⭐️ 256
🕓 5 weeks ago
macOS
.package(url: "https://github.com/CreateAPI/CreateAPI.git", from: "0.1.0")

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 carefully written by hand
  • Reliable: tested on 1KK lines of publicly available OpenAPI specs producing correct code every time
  • Customizable: offers a ton of customization options

Powered by OpenAPIKit

Installation

Mint

$ mint install CreateAPI/CreateAPI

Homebrew

$ brew install create-api

Swift Package Plugins

Make

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

Getting Started

You'll need an OpenAPI schema (using 3.0.x) for your API. If your schema has external references, you might also need to bundle it beforehand.

If you have never used CreateAPI before, be sure to check out our tutorial: Generating an API with CreateAPI

CreateAPI can generate complete Swift Package bundles but can also generate individual components to integrate into an existing project. Either way, you'll want to use the generate command:

$ create-api generate --help
USAGE: create-api generate <input> [--output <output>] [--config <config>] [--config-option <config-option> ...] [--verbose] [--strict] [--allow-errors] [--clean] [--watch] [--single-threaded] [--measure]

ARGUMENTS:
  <input>                 The path to the OpenAPI spec in either JSON or YAML format

OPTIONS:
  --output <output>       The directory where generated outputs are written (default: CreateAPI)
  --config <config>       The path to the generator configuration. (default: .create-api.yaml)
  --config-option <config-option>
                          Option overrides to be applied when generating.

        In scenarios where you need to customize behaviour when invoking the generator, use this option to
        specify individual overrides. For example:

        --config-option "module=MyAPIKit"
        --config-option "entities.filenameTemplate=%0DTO.swift"

        You can specify multiple --config-option arguments and the value of each one must match the
        'keyPath=value' format above where keyPath is a dot separated path to the option and value is the
        yaml/json representation of the option.

  -v, --verbose           Enables verbose log messages
  --strict                Treats warnings as errors and fails generation
  --allow-errors          Ignore errors that occur during generation and continue if possible
  -c, --clean             Removes the output directory before writing generated outputs
  --watch                 Monitor changes to both the spec and the configuration file and automatically
                          regenerate outputs
  --single-threaded       Disables parallelization
  --measure               Measure performance of individual operations and log timings
  --version               Show the version.
  -h, --help              Show help information.

To try CreateAPI out, run the following commands:

$ curl "https://petstore3.swagger.io/api/v3/openapi.json" > schema.json
$ create-api generate schema.json --config-option module=PetstoreKit --output PetstoreKit
$ cd PetstoreKit
$ swift build

There you have it, a comping Swift Package ready to be integrated with your other Swift projects!

For more information about using CreateAPI, check out the Documentation.

Projects using CreateAPI

Need some inspiration? Check out the list of projects below that are already using CreateAPI:

Are you using CreateAPI in your own open-source project? Let us know by adding it to the list above!

Contributing

We always welcome contributions from the community via Issues and Pull Requests. Please be sure to read over the contributing guidelines for more information.

GitHub

link
Stars: 256
Last commit: 1 week ago
jonrohan Something's broken? Yell at me @ptrpavlik. Praise and feedback (and money) is also welcome.

Release Notes

0.1
6 weeks ago

CreateAPI 0.1 makes some big changes to help prepare for even more features and enhancements. To make this possible, we've had to revisit a lot of parts of the way that the generator is used and while at the core there hasn't been much change, it's likely that you will need to adjust your configuration files and the way that you use the cli. For more details, please refer to the release notes below.

As always, if you have any problems then please feel free to create a new issue!

Enhancements

  • #69 - Publish release to Homebrew.
  • #48 - Support Swift Package Plugins.
  • #58 - Improve readme, add usage documentation and contributing guides.
  • #47 - Override any option in the configuration file from the command line using --config-option.
  • #85 - Add custom package dependencies in generated package.
  • #114 - Allow custom mapping between schema data types/formats and Swift types used in generation.
  • #125 - Raise an error if the --config file doesn't exist instead of silently falling back to the default options.
  • #90 - Produce warnings when configuration files contain unknown or deprecated options.
  • #76 - Add --version option/command.
  • #71 - Support excluding individual properties on entities.
  • #116, #141 - Write extension source files into Extensions directory and improve their filenames.
  • #131 - Raise an error if you use --clean when the --output directory also contains the schema or config file.
  • #138 - Trim whitespace from the fileHeaderComment.
  • #140 - Run path generation in parallel.

Breaking Changes

  • #83 - Generated packages and paths now depend on Get 1.0.2 or later. If you don't use Get, your Request type must expose an initializer that matches the initializer defined in Get.
  • #88 - When generating a Swift Package, the Package.swift file and all other sources are written to the root of the --output directory instead of being nested inside a subdirectory.
  • #132 Default output directory is now ./CreateAPI when --output is not specified.
  • #112 - The rename.properties option now understands property names as defined in the original schema and not after applying CreateAPI transformations (such as case conversion or swifty style booleans).
  • #125 - The generator will now error if the path defined using --config did not contain a valid file (prior behaviour was to fallback to the default configuration).
  • #47 - Command Line Argument options that alter the generate output have now been moved into the configuration file and the behaviour may have also been adjusted.
    • --split (-s) is now the default behavior. Use the mergeSources option to merge generated source files.
    • --filename-template has been replaced by the entities.filenameTemplate and paths.filenameTemplate options.
    • --entityname-template has been replaced by the entities.nameTemplate option.
    • --generate has been replaced by the generate option and now accepts paths, entities, enums and package to customize which components are generated.
    • --package and --module have been incorporated as part of the generate option (see above) for controlling the generated outputs and the module/package name is configured using the module option.
    • --vendor has been replaced by the vendor option.
  • #100 - For entities, isGeneratingStructs and isMakingClassesFinal have merged into a single defaultType option (accepted values struct, class or finalClass).
    • isGeneratingMutableClassProperties and isGeneratingMutableStructProperties have been replaced by a single mutableProperties option. Specify true, false, structs or classes instead.
    • entitiesGeneratedAsClasses and entitiesGeneratedAsStructs have been replaced by a single typeOverrides option.
  • #98 - comments options have been replaced with a single commentOptions property that accepts false, true or an array containing any of [title, description, example, externalDocumentation, capitalized].
  • #97 - isReplacingCommonAcronyms, addedAcronyms and ignoredAcronyms have been replaced with a single acronyms option.
  • #94 - isSwiftLintDisabled has been removed. Use fileHeaderComment if you want to replicate this behavior.
  • #93 - isAdditionalPropertiesOnByDefault has been removed with no replacement.
  • #92 - Every generated Request now includes its operationId and the isAddingOperationIds option has now been removed.
  • #91 - Fixed a spelling mistake in overridenResponses and overridenBodyTypes.
  • #63 - isInliningPropertiesFromReferencedSchemas behavior is now enabled by default and the option has renamed to inlineReferencedSchemas.
  • #75 - isGeneratingCustomCodingKeys behavior is now enabled by default and the option has been renamed to optimizeCodingKeys.
  • #66 - access no longer accepts an open string. The value must be either internal or public.
  • #114, #145 - isUsingIntegersWithPredefinedCapacity has been removed. You can now configure data type mappings to Swift types using the dataTypes option.
  • #134 - isGeneratingEnums has been removed and is now configurable as part of the new generate option.
  • #89 - Swifty style boolean properties in the configuration file have been renamed.
    • isNaiveDateEnabled useNaiveDate
    • isPluralizationEnabled pluralizeProperties
    • isInliningTypealiases inlineTypealiases
    • isGeneratingSwiftyBooleanPropertyNames useSwiftyPropertyNames
    • isAddingDeprecations annotateDeprecations
    • entities
      • isStrippingParentNameInNestedObjects stripParentNameInNestedObjects
      • isAddingDefaultValues includeDefaultValues
      • isSortingPropertiesAlphabetically sortPropertiesAlphabetically
      • isGeneratingEncodeWithEncoder alwaysIncludeEncodableImplementation
      • isGeneratingInitWithDecoder alwaysIncludeDecodableImplementation
      • isGeneratingInitializers includeInitializer
      • isSkippingRedundantProtocols skipRedundantProtocols
      • isGeneratingIdentifiableConformance includeIdentifiableConformance
    • paths
      • isRemovingRedundantPaths removeRedundantPaths
      • isMakingOptionalPatchParametersDoubleOptional makeOptionalPatchParametersDoubleOptional
      • isInliningSimpleQueryParameters inlineSimpleQueryParameters
      • isInliningSimpleRequests inlineSimpleRequests
      • isGeneratingResponseHeaders includeResponseHeaders
      • isGeneratingCustomCodingKeys optimizeCodingKeys
      • isInliningPropertiesFromReferencedSchemas inlineReferencedSchemas

Refer to the Configuration Options documentation for more information.

Internal

  • #79 - Lint project using SwiftLint.
  • #81 - Compile generated test snapshots on Linux as part of CI checks.
  • #117 - Refactor file writing responsibility out of the Generate command.
  • #122 - Cleanup tests with new snapshot(spec:name:testCompilationOnLinux:arguments:configuration:) method.
  • #120 - Use swift-configuration-parser library.
  • #128 - Refactor CreateAPITests structure and rewrite snapshotter.
  • #123 - Automatically update AllPackages package when rerecording snapshots.
  • #129 - Introduce 'Record Snapshots' scheme to simplify rerecording snapshots.

Full Changelog: https://github.com/CreateAPI/CreateAPI/compare/0.0.5...0.1.0

Artifact Bundle

Checksum: 4e9d1fb023c52e423d57de0928da5d943e3e4c81f6cb903523654867e6372db7

.binaryTarget(
    name: "create-api",
    url: "https://github.com/CreateAPI/CreateAPI/releases/download/0.1.0/create-api.artifactbundle.zip",
    checksum: "4e9d1fb023c52e423d57de0928da5d943e3e4c81f6cb903523654867e6372db7"
)

Swiftpack is being maintained by Petr Pavlik | @ptrpavlik | @swiftpackco | API | Analytics