Support intra document references https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#reference-object

I think most people uses this, even the petstore example uses this.

The failure crate appears to be deprecated these days and has drawbacks including incompatibilities with std::error::Error. For users, it might be inconvenient to have to deal with error types that don’t implement std::error::Error.

For this reason, this replaces the failure crate entirely. In the library part, thiserror is used instead, which also makes the generation of the error type short and convenient (even taking care of the From implementations), without exposing any thiserror specifics to the user.

In the example, anyhow now takes care of printing nicely formatted error messages, including error causes and (if provided with RUST_BACKTRACE=1) an error backtrace.

Also, the error-chain dependency isn’t used anymore, so let’s remove it.

Added way to collect referenced schemas in another files (local).

This is used by my other project which leverages this to generate models from openapi spec. In case this feature does not fit this lib, I'll migrate the code to my project instead

• https://swagger.io/specification/v2/#externalDocumentationObject
• https://github.com/OAI/OpenAPI-Specification/blob/master/examples/v2.0/json/petstore-with-external-docs.json#L18-L21
• https://idratherbewriting.com/learnapidoc/pubapis_openapi_step8_externaldocs_object.html

This PR adds the required implementation for OpenAPI v3.0.1. Should fix #7, or at least partially.

In addition to v3.0, this PR adds two new tests (one for v2 and one for v3.0).

Those two tests will deserialize and re-serialize input files to a JSON string through two different paths, comparing the result.

1. File -> String -> serde_yaml::Value -> serde_json::Value -> String
2. File -> Spec -> serde_json::Value -> String Both conversions of serde_json::Value -> String are done using serde_json::to_string_pretty.

Since the first conversion is independant of the current crate (and only uses serde's json and yaml support), no information should be lost in the final JSON string.

The second conversion goes through the OpenApi enum, so the final JSON string is a representation of the crate implementation.

By comparing those two JSON conversions, we can validate the implementation. JSON files will be located in:

target/tests/can_deserialize_and_reserialize_v3/{yaml_to_json,yaml_to_spec_to_json}/

Note that the official examples for https://github.com/OAI/OpenAPI-Specification/tree/29ea26df7dfd8def1605521f5f32c692a642de79/examples/v3.0 are added to the data/v3.0 directory.

Those two tests exposes issues not only with the new v3.0 implementation but also with the previous v2 one.

Missing from v2:

• k8s.json:
  • additionalProperties
  • x-*
  • operationId
  • Probably others? File is 1.6 MB
• petstore-simple.json:
  • allOf
  • termsOfService
  • operationId
• petstore_minimal.json:
  • termsOfService
• rocks.json:
  • termsOfService
  • operationId
  • default
• uber.json:
  • security

Missing from v3.0:

• api-with-examples.json:
  • examples
• callback-example.json:
  • callbacks
• link-example.json:
  • operationId
  • parameters
• petstore-expanded.json:
  • allOf
  • termsOfService
  • style
• petstore.json:
  • Nothing!
• uspto.json:
  • example
  • default
  • server variables

Note that CI will fail because of those tests. Let me know if you want me to disable the assertion to let the CI pass.

Note that the first commit in this PR (acf8463) is part of PR #19 and ed759ee is PR #20. As such it should either be merged after those two others or be the only one merged.

Last commit on master (a33e084) breaks compilation:

   Compiling openapi v0.1.5 (file:///${HOME}/openapi.git)
error[E0412]: cannot find type `Operations` in this scope
  --> src/schema.rs:47:33
   |
47 |     pub paths: BTreeMap<String, Operations>,
   |                                 ^^^^^^^^^^ did you mean `Operation`?

error[E0412]: cannot find type `Operations` in this scope

Looking at a33e084 it seems the Operations was renamed to PathItem? This commit simply rename Operations to PathItem for Spec::paths.

Allows to do spec.clone() . Maybe I should not need to do this in my code so not sure if this is a good addition or not.

Also, please release 0.1.6 when you can.

• Added some files from https://github.com/OAI/OpenAPI-Specification/tree/master/examples/v2.0/yaml
• A test that just deserializes them.

If the deserializer is broken, it will panic (hopefully) and the test will fail.

Some schema validation fields are missing or not implemented according to the JSON schema validation specification (which is used in several parts of the OpenAPI 3.0 specification). This adds the missing fields and fixes the type of minimum, which may only take integers and not arbitrary schemas.

Notes

• As the JSON schema validation specification only mentions that pattern “SHOULD” be a valid regular expression, I suggest representing it as a plain String.
• Newer versions of the JSON schema validation specification change the type of exclusiveMinimum and exclusiveMaximum from Boolean to integer. To comply with OpenAPI 3.0, we have to stick with Booleans for now.

The OpenAPI specification defines the additionalProperties field according to the JSON schema specification. In the version of the JSON schema specification referenced by the OpenAPI specification, the value of additionalProperties may be either Boolean or a schema (though it appears that newer versions of the JSON schema specification no longer allow Boolean values).

However, to comply with OpenAPI 3.0, this adjusts the representation of the additionalProperties field in this crate accordingly

Added to schema (from openapi 3 spec)

• oneOf, anyOf, not
• maxLength, minLength
• extensions map: this map will include all additional fields that are defined in the model. This field is flattened so serialization/deserialization works as intended

Fixed failing travis build job

This PR uses the derive_builder crate to derive builder classes for all structs. This enables writing an OpenApi Spec in a much more readable and straight forward fashion (No need to explicitly set parts of the struct to None or creating a mutable struct via default and then just editing the desired fileds). This is useful when using this crate to generate an openapi spec instead of parsing it from a file.

Example with Builders:

use openapi::OpenApi;
use openapi::v3_0::{ComponentsBuilder, ContactBuilder, InfoBuilder, OperationBuilder, ParameterBuilder, PathItemBuilder, ServerBuilder, SpecBuilder};

let spec = SpecBuilder::default()
	.openapi("3.0.1".to_string())
	.info(InfoBuilder::default()
			.title("Example Api".to_string())
			.version(clap::crate_version!().to_string())
			.contact(ContactBuilder::default()
					.name("Support".to_string())
					.email("[email protected]".to_string())
					.build().unwrap()
			)
			.build().unwrap()
	)
	.servers(vec![ ServerBuilder::default()
					.url("https://api.example.com")
					.build().unwrap()
			]
	)
	.paths(api_paths)
	.build().unwrap();

OpenApi::V3_0(spec)

Commit e2d506c ("Replace failure dependency with thiserror/anyhow") already replaced the use of obsolete failure crate, but let's also remove it from dependencies.

Added:

• Support for deprecated operations in V2
  • see https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#fixed-fields-5
• Support for deprecated parameters in V3
  • see https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md#fixed-fields-10
• Support for deprecated schemas in V3
  • see https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md#fixed-fields-20

1. Enums can hold any value: boolean, strings, numbers...so just use JsonValue
2. Items can point to Ref so wrap Schema inside ObjectOrReference
3. Reorder ObjectOrReference because they are untagged, its better to check for Ref first

Signed-off-by: Hanif Ariffin [email protected]