Merge pull request #63 from mattpolzin/refactor-context-names

1.0.0 Release

Author: mattpolzin

LICENSE.txt

@@ -1,4 +1,4 @@
-Copyright 2018 Mathew Polzin
+Copyright 2020 Mathew Polzin
 
 Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
 

Package.swift

@@ -1,5 +1,4 @@
 // swift-tools-version:5.1
-// The swift-tools-version declares the minimum version of Swift required to build this package.
 
 import PackageDescription
 

README.md

@@ -31,9 +31,9 @@ A library containing Swift types that encode to- and decode from [OpenAPI](https
 	- [Components Object (`OpenAPI.Components`)](#components-object-openapicomponents)
 	- [Paths Object (`OpenAPI.PathItem.Map`)](#paths-object-openapipathitemmap)
 	- [Path Item Object (`OpenAPI.PathItem`)](#path-item-object-openapipathitem)
-	- [Operation Object (`OpenAPI.PathItem.Operation`)](#operation-object-openapipathitemoperation)
+	- [Operation Object (`OpenAPI.Operation`)](#operation-object-openapipathitemoperation)
 	- [External Document Object (`OpenAPI.ExternalDoc`)](#external-document-object-openapiexternaldoc)
-	- [Parameter Object (`OpenAPI.PathItem.Parameter`)](#parameter-object-openapipathitemparameter)
+	- [Parameter Object (`OpenAPI.Parameter`)](#parameter-object-openapipathitemparameter)
 	- [Request Body Object (`OpenAPI.Request`)](#request-body-object-openapirequest)
 	- [Media Type Object (`OpenAPI.Content`)](#media-type-object-openapicontent)
 	- [Encoding Object (`OpenAPI.Content.Encoding`)](#encoding-object-openapicontentencoding)
@@ -101,10 +101,10 @@ The types used by this library largely mirror the object definitions found in th
 At the root there is an `OpenAPI.Document`. In addition to some information that applies to the entire API, the document contains `OpenAPI.Components` (essentially a dictionary of reusable components that can be referenced with `JSONReferences`) and an `OpenAPI.PathItem.Map` (a dictionary of routes your API defines).
 
 #### Routes
-Each route is an entry in the document's `OpenAPI.PathItem.Map`. The keys of this dictionary are the paths for each route (i.e. `/widgets`). The values of this dictionary are `OpenAPI.PathItems` which define any combination of endpoints (i.e. `GET`, `POST`, `PATCH`, etc.) that the given route supports.
+Each route is an entry in the document's `OpenAPI.PathItem.Map`. The keys of this dictionary are the paths for each route (i.e. `/widgets`). The values of this dictionary are `OpenAPI.PathItems` which define any combination of endpoints (i.e. `GET`, `POST`, `PATCH`, etc.) that the given route supports. In addition to accessing endpoints on a path item under the name of the method (`.get`, `.post`, etc.), you can get an array of pairs matching endpoint methods to operations with the `.endpoints` method on `PathItem`.
 
 #### Endpoints
-Each endpoint on a route is defined by an `OpenAPI.PathItem.Operation`. Among other things, this operation can specify the parameters (path, query, header, etc.), request body, and response bodies/codes supported by the given endpoint.
+Each endpoint on a route is defined by an `OpenAPI.Operation`. Among other things, this operation can specify the parameters (path, query, header, etc.), request body, and response bodies/codes supported by the given endpoint.
 
 #### Request/Response Bodies
 Request and response bodies can be defined in great detail using OpenAPI's derivative of the JSON Schema specification. This library uses the `JSONSchema` type for such schema definitions.
@@ -183,7 +183,7 @@ For example,
 let apiDoc: OpenAPI.Document = ...
 let addBooksPath = apiDoc.paths["/cloudloading/addBook"]
 
-let addBooksParameters: [OpenAPI.PathItem.Parameter]? = addBooksPath?.parameters.compactMap(apiDoc.components.dereference)
+let addBooksParameters: [OpenAPI.Parameter]? = addBooksPath?.parameters.compactMap(apiDoc.components.dereference)
 ```
 
 ## Notes
@@ -275,7 +275,7 @@ See [**A note on dictionary ordering**](#a-note-on-dictionary-ordering) before d
 - [x] trace
 - [x] specification extensions (`vendorExtensions`)
 
-### Operation Object (`OpenAPI.PathItem.Operation`)
+### Operation Object (`OpenAPI.Operation`)
 - [x] tags
 - [x] summary
 - [x] description
@@ -295,7 +295,7 @@ See [**A note on dictionary ordering**](#a-note-on-dictionary-ordering) before d
 - [x] url
 - [ ] specification extensions
 
-### Parameter Object (`OpenAPI.PathItem.Parameter`)
+### Parameter Object (`OpenAPI.Parameter`)
 - [x] name
 - [x] in (`context`)
 - [x] description
@@ -387,7 +387,7 @@ See [**A note on dictionary ordering**](#a-note-on-dictionary-ordering) before d
     - [x] local (same file) reference (`internal` case)
         - [x] encode
         - [x] decode
-        - [ ] dereference
+        - [x] dereference
     - [x] remote (different file) reference (`external` case)
         - [x] encode
         - [x] decode
@@ -396,7 +396,7 @@ See [**A note on dictionary ordering**](#a-note-on-dictionary-ordering) before d
 ### Schema Object (`JSONSchema`)
 - [x] Mostly complete support for JSON Schema inherited keywords
 - [x] nullable
-- [ ] discriminator
+- [x] discriminator
 - [x] readOnly (`permissions` `.readOnly` case)
 - [x] writeOnly (`permissions` `.writeOnly` case)
 - [ ] xml

Sources/OpenAPIKit/Component Object/Components+JSONReference.swift

@@ -65,6 +65,16 @@ extension OpenAPI.Components {
         }
     }
 
+    /// Pass a reference to a component.
+    /// `dereference()` will return the component value if it is found
+    /// in the Components Object.
+    ///
+    /// - Important: Dereferencing an external reference (i.e. one that points to another file)
+    ///     is not currently supported by OpenAPIKit and will therefore always result in `nil`.
+    public func dereference<ReferenceType: ComponentDictionaryLocatable>(_ reference: JSONReference<ReferenceType>) -> ReferenceType? {
+        return self[reference]
+    }
+
     /// Create a `JSONReference`.
     ///
     /// - throws: If the given name does not refer to an existing component of the given type.

Sources/OpenAPIKit/Component Object/Components+Locatable.swift

@@ -28,7 +28,7 @@ extension OpenAPI.Response: ComponentDictionaryLocatable {
     public static var openAPIComponentsKeyPath: KeyPath<OpenAPI.Components, OpenAPI.ComponentDictionary<Self>> { \.responses }
 }
 
-extension OpenAPI.PathItem.Parameter: ComponentDictionaryLocatable {
+extension OpenAPI.Parameter: ComponentDictionaryLocatable {
     public static var openAPIComponentsKey: String { "parameters" }
     public static var openAPIComponentsKeyPath: KeyPath<OpenAPI.Components, OpenAPI.ComponentDictionary<Self>> { \.parameters }
 }

Sources/OpenAPIKit/Component Object/Components.swift

@@ -18,7 +18,7 @@ extension OpenAPI {
 
         public var schemas: ComponentDictionary<JSONSchema>
         public var responses: ComponentDictionary<Response>
-        public var parameters: ComponentDictionary<PathItem.Parameter>
+        public var parameters: ComponentDictionary<Parameter>
         public var examples: ComponentDictionary<Example>
         public var requestBodies: ComponentDictionary<Request>
         public var headers: ComponentDictionary<Header>
@@ -35,7 +35,7 @@ extension OpenAPI {
 
         public init(schemas: ComponentDictionary<JSONSchema> = [:],
                     responses: ComponentDictionary<Response> = [:],
-                    parameters: ComponentDictionary<PathItem.Parameter> = [:],
+                    parameters: ComponentDictionary<Parameter> = [:],
                     examples: ComponentDictionary<Example> = [:],
                     requestBodies: ComponentDictionary<Request> = [:],
                     headers: ComponentDictionary<Header> = [:],
@@ -163,7 +163,7 @@ extension OpenAPI.Components: Decodable {
             responses = try container.decodeIfPresent(OpenAPI.ComponentDictionary<OpenAPI.Response>.self, forKey: .responses)
                 ?? [:]
 
-            parameters = try container.decodeIfPresent(OpenAPI.ComponentDictionary<OpenAPI.PathItem.Parameter>.self, forKey: .parameters)
+            parameters = try container.decodeIfPresent(OpenAPI.ComponentDictionary<OpenAPI.Parameter>.self, forKey: .parameters)
             ?? [:]
 
             examples = try container.decodeIfPresent(OpenAPI.ComponentDictionary<OpenAPI.Example>.self, forKey: .examples)

Sources/OpenAPIKit/Content.swift renamed to Sources/OpenAPIKit/Content/Content.swift

@@ -10,7 +10,7 @@ extension OpenAPI.Content {
     /// 
     /// See [OpenAPI Encoding Object](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.3.md#encoding-object).
     public struct Encoding: Equatable {
-        public typealias Style = OpenAPI.PathItem.Parameter.Schema.Style
+        public typealias Style = OpenAPI.Parameter.SchemaContext.Style
 
         public let contentType: OpenAPI.ContentType?
         public let headers: OpenAPI.Header.Map?

Sources/OpenAPIKit/ContentEncoding.swift renamed to Sources/OpenAPIKit/Content/ContentEncoding.swift

@@ -286,20 +286,20 @@ internal func decodeSecurityRequirements<CodingKeys: CodingKey>(from container:
 
 internal func validateSecurityRequirements(in paths: OpenAPI.PathItem.Map, against components: OpenAPI.Components) throws {
     for (path, pathItem) in paths {
-        for (verb, operation) in pathItem.endpoints {
-            if let securityRequirements = operation.security {
+        for endpoint in pathItem.endpoints {
+            if let securityRequirements = endpoint.operation.security {
                 try validate(
                     securityRequirements: securityRequirements,
                     at: path,
-                    for: verb,
+                    for: endpoint.method,
                     against: components
                 )
             }
         }
     }
 }
 
-internal func validate(securityRequirements: [OpenAPI.SecurityRequirement], at path: OpenAPI.Path, for verb: OpenAPI.HttpVerb, against components: OpenAPI.Components) throws {
+internal func validate(securityRequirements: [OpenAPI.SecurityRequirement], at path: OpenAPI.Path, for verb: OpenAPI.HttpMethod, against components: OpenAPI.Components) throws {
     let securitySchemes = securityRequirements.flatMap { $0.keys }
 
     for securityScheme in securitySchemes {