Swiftpack.co - Apodini/Apodini as Swift Package

Swiftpack.co is a collection of thousands of indexed Swift packages. Search packages.
Apodini/Apodini
Apodini - A declarative, composable server-side Swift framework
.package(url: "https://github.com/Apodini/Apodini.git", from: "0.5.1")

Apodini

DOI codecov jazzy Build and Test

Apodini is a declarative, composable framework to build web services using Swift. It is part of a research project at the TUM Research Group for Applied Software Engineering.

Getting Started

Installation

Apodini uses the Swift Package Manager:

Add it as a project-dependency:

dependencies: [
    .package(url: "https://github.com/Apodini/Apodini.git", .branch("develop"))
]

Add the base package and all exporters you want to use to your target:

targets: [
    .target(
        name: "Your Target",
        dependencies: [
            .product(name: "Apodini", package: "Apodini"),
            .product(name: "ApodiniREST", package: "Apodini"),
            .product(name: "ApodiniOpenAPI", package: "Apodini")
        ])
]‚

Hello World

Getting started is really easy:

import Apodini
import ApodiniREST

struct Greeter: Handler {
    @Parameter var country: String?

    func handle() -> String {
        "Hello, \(country ?? "World")!"
    }
}

struct HelloWorld: WebService {
    var configuration: Configuration {
        REST()
    }

    var content: some Component {
        Greeter()
    }
}

HelloWorld.main()

// http://localhost:8080/v1 -> Hello, World!
// http://localhost:8080/v1?country=Italy -> Hello, Italy!

Apodini knows enough about your service to automatically generate OpenAPI docs. Just add the respective exporter:

import ApodiniOpenAPI
...
struct HelloWorld: WebService {
    var configuration: Configuration {
        REST { 
            OpenAPI()
        }
    }
    ...
}

// JSON definition: http://localhost:8080/openapi
// Swagger UI: http://localhost:8080/openapi-ui

With Bindings we can re-use Handlers in different contexts:

struct Greeter: Handler {
    @Binding var country: String?

    func handle() -> String {
        "Hello, \(country ?? "World")!"
    }
}

struct HelloWorld: WebService {
    var configuration: Configuration {
        REST { 
            OpenAPI()
        }
    }

    var content: some Component {
        Greeter(country: nil)
            .description("Say 'Hello' to the World.")
        Group("country") {
            CountrySubsystem()
        }
    }
}

struct CountrySubsystem: Component {
    @PathParameter var country: String
    
    var content: some Component {
        Group($country) {
            Greeter(country: Binding<String?>($country))
                .description("Say 'Hello' to a country.")
        }
    }
}

// http://localhost:8080/v1 -> Hello, World!
// http://localhost:8080/v1/country/Italy -> Hello, Italy!

Apodini allows the developer to specify CLI-arguments that are passed to the WebService. The arguments can for example be used in Configuration:

struct HelloWorld: WebService {
    @Flag(help: "Generate an OpenAPI documentation of the WebService.")
    var generateOpenAPIDocs = false
    
    var configuration: Configuration {
        if(generateOpenAPIDocs) {
            REST { 
                OpenAPI()
            }
        } else {
            REST()
        }
    }
}

For further information on how to specify CLI-arguments see https://github.com/apple/swift-argument-parser

Documentation

The framework is in early alpha phase. You can inspect the current development manifestos describing the framework in the documentation folder

You can find a generated technical documentation for the different Swift types at https://apodini.github.io/Apodini

Contributing

Contributions to this project are welcome. Please make sure to read the contribution guidelines first.

License

This project is licensed under the MIT License. See License for more information.

Code of conduct

For our code of conduct see Code of conduct

GitHub

link
Stars: 48
Last commit: 9 hours ago

Ad: Job Offers

iOS Software Engineer @ Perry Street Software
Perry Street Software is Jack’d and SCRUFF. We are two of the world’s largest gay, bi, trans and queer social dating apps on iOS and Android. Our brands reach more than 20 million members worldwide so members can connect, meet and express themselves on a platform that prioritizes privacy and security. We invest heavily into SwiftUI and using Swift Packages to modularize the codebase.

Submit a free job ad (while I'm testing this). The analytics numbers for this website are here.

Release Notes

0.5.1
4 days ago

Semantic Version Minor

  • Adding Metadata support to add OpenAPI Security schemes and requirements @Supereg (#340)

    Release Notes

    ApodiniOpenAPI can now document security schemes and security requirements. If you use ApodiniAuthorization, particularly the BasicAuthenticationScheme or BearerAuthenticationScheme (this includes ApodiniAuthorizationJWT), you do not need to do anything and authentication requirements are documented automatically. You may want to look into the initialisers of BasicAuthenticationScheme and BearerAuthenticationScheme if you want to modify naming, add documentation to the security scheme or adding vendor extensions.

    To add security schemes manually, look at the Security Metadata. Here are a few examples:

    • Adding API Key from a query @Parameter: Security(name: "api_key", .apiKey(at: $myApiKeyParameter))
    • Adding arbitrary API Key: Security(name: "api_key", .apiKey(name: "X-Api-Key-Header", location. header))
    • Documenting HTTP Digest auth: Security(name: "digest", .http(scheme: "digest"))
    • OpenID Connect URL to OAuth2 requirements: Security(name: "my_auth", .openIdConnect(url: ...))
    • OAuth2 flows: Security(name: "my_oauth", .oauth2(flows: ...))
  • ApodiniMigrator @eldcn (#345)

    Release Notes

    This PR introduces ApodiniMigration target. It adds a dependency to ApodinIMigrator framework, which handles automated library generation, migration guide generation and automated migration of the client library by means of the migration guide. Relevant part of the functionality in Apodini is solely retrieval of API related information in form of simplified Document (similar to OpenAPI), which is further used to support the above mentioned tasks.

  • Use Metadata to provide improved JSON Schemas in OpenAPI @Supereg (#349)

    Release Notes This PR adds the following new Metadata to the `ApodiniOpenAPI` target:

    Handler Metadata

    • Summary(_:)

    Component Metadata

    • ParameterDescription(for:_:)
    • Tags(_:) (this complements the already existent .tags modifier)

    Content Metadata

    Each of those Metadata can be declared on the Metadata declaration blocks of Content types. Typically, each of those Metadata provide a initilizer to apply to the Content type itself or to apply to one of its properties. As parameter name can't be derived from Swift KeyPaths, you always need to supply both: a KeyPath to the property and the type name in string representation.

    • Applying for all Schemas:
      • Description(_:) or Description(of:_:propertyName:)
      • MarkDeprecated(_:) or MarkDeprecated(property:_:propertyName:)
      • Example(_:) or Example(for:_:propertyName:)
    • Applying to Numeric and Integer Schemas:
      • Maximum(of:is:exclusive:propertyName:)
      • Minimum(of:is:exclusive:propertyName:)
      • MultipleOf(of:is:propertyName:)
    • Applying to String Schemas:
      • MaxLength(of:is:propertyName:)
      • MinLength(of:is:propertyName:)
      • Pattern(of:is:propertyName:)
  • Fix #318 @theMomax (#346)

    Release Notes

    Automatic detection of CommunicationalPattern was improved. This might change the behavior of some endpoints, if they make use of State, ObservedObject, Environment(\.connection), or any Environment/EnvironmentObject that contains a ObservableObject. In some cases manually setting the CommunicationalPattern via metadata may become redundant. In edge-cases it may happen that the previous, simple heuristic made the correct choice, whereas the new heuristic assumes the pattern to be a different one. In that case you have to explicitly specify the Pattern via metadata on your Handler.

Other Changes

  • Update Deployment providers to cli changes + Test cases @hendesi (#341)
  • Remove Unneeded Build Flags @PSchmiedmayer (#344)
  • Split out the Metadata System into separate targets @Supereg (#347)
  • OpenAPI TypeInformation @eldcn (#348)
  • Update dependencies @ApodiniBot (#350)
  • Add DocC documentation for Metadata, ApodiniAuthorization and Information API @Supereg (#352)
  • Filter process list to only include TCP state LISTEN @moritzsternemann (#358)
  • Update dependencies @ApodiniBot (#359)
  • Update dependencies @ApodiniBot (#360)
  • Fix small typo "InterfaceExporerKey" @ridvan-cln (#361)

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