CHANGELOG.md
# Fury Swagger Parser Changelog
## 0.22.7 (2018-12-11)
### Bug Fixes
- Adds support for generating JSON bodies for schemas where the root is an
array. For example, given following array schema:
```yaml
type: array
items:
type: string
example: Doe
```
The parser will now generate a JSON body of `["Doe"]` whereas in previous
versions would've resulted in an empty array.
- Fixes parsing Swagger documents that contain properties called `$ref`.
Previously the parser would attempt to dereference the property as would
generically try to dereference any key in an object called `$ref`, as per the
JSON Schema specification, references are only permitted when a schema type
is expected.
For example, the following is a schema which is trying to describe an object
with a property called `$ref`, previously the parser would attempt to
dereference `$ref` and crash in the process.
```yaml
type: object
properties:
$ref:
type: string
example: '#/definitions/User'
required: ['$ref']
```
There is a still an open known issue
[#235](https://github.com/apiaryio/fury-adapter-swagger/issues/235) that
uses of `$ref` in a Swagger 2 document where the value a string will cause
the parser to attempt to dereference it incorrectly when the `$ref` property
is found on an object that does not support `$ref` as per the Swagger 2 and
JSON Schema specifications.
## 0.22.6 (2018-12-07)
### Enhancements
- While generating a data structure from a Swagger Schema, we will now attempt
to infer when the schema should be an object but the user has forgotten to
put `type: object` by looking for the presence of `properties` in the schema.
- Adds support for object inheritance and mixins via `allOf` referencing in
data structure generation.
For example, the following will create an object which inherits from `User`:
```yaml
allOf:
- $ref: '#/definitions/User'
- properties:
id:
type: string
```
Secondly, when you reference multiple objects using `allOf` they will be
treated as mixins:
```yaml
allOf:
- $ref: '#/definitions/BaseUser'
- $ref: '#/definitions/UserMixin'
```
### Bug Fixes
- Fixes using `x-nullable` in a schema which previously caused the schema not
to be converted to a data structure. For example, the following schema
wouldn't result in a data structure:
```yaml
type: string
x-nullable: true
```
- Fixes some cases where rendering a JSON example from a Swagger Schema using
example values which contain references would fail.
## 0.22.4 (2018-11-29)
### Bug Fixes
- Fixes a regression introduced in 0.22.3 which caused a reference (`$ref`)
from a definition to another definitions example value to fail.
## 0.22.3 (2018-11-27)
### Bug Fixes
- Example values in nested Schema Object will now be used for JSON body
generation.
## 0.22.2 (2018-10-25)
- Fixes a regression introduced in 0.22.0 where using `$ref` directly inside a
Swagger Schema found within the `definitions` section would cause a parsing
failure.
## 0.22.1 (2018-10-22)
### Bug Fixes
- Fixes a regression introduced in 0.22.0 where the parse result may contain
invalid references inside a JSON Schema for example values if they used
references. This regression also caused `$ref` to be incorrectly present in
Data Structure sample values.
## 0.22.0 (2018-10-11)
### Enhancements
- Adds a dataStructures section to the parse result containing every data
structure found within the definitions section of a Swagger document. We now
use referencing between data structures found within a request or response
data structure which generally makes parse results smaller instead of
duplicating the data structure contents.
### Bug Fixes
- Adds support for primitive request bodies.
## 0.21.1 (2018-09-10)
### Bug Fixes
- No longer expand all option values (properties, array values) etc in the case
that a schema has a circular reference.
## 0.21.0 (2018-09-07)
### Enhancements
- Line and column numbers are now exposed in the parse result in source maps
for annotation elements.
### Bug Fixes
- Default and example values for headers are now validated to match the header
type. For example, placing a string as a value for a number type header will
now emit a warning.
- Header values will now contain source map information in the parse result.
- Fix support for type `file` in multipart-form body generation.
## 0.20.0 (2018-09-04)
### Enhancements
- The API Version is now exposed in the parse result. The API category now
contains a version attribute including the API version.
- Circular references are now supported in schemas and JSON and JSON Schemas
will now be present in parse results when you use circular references.
### Bug Fixes
- Example values in a Schema Object will now be placed into the dataStructure
as a value instead of inside samples in cases where there isn't already a
value.
## 0.19.2
### Bug Fixes
- Return an error in the parse result when the source API Description Document
is not an object. Previously an error was thrown.
- When a request or response body has a schema of `format: binary` then we no
longer generate a JSON Schema in the parse result. A JSON Schema for binary
types doesn't make sense as you cannot place binary data in JSON.
- Example values found in schemas are now translated into examples in
generated JSON Schema exposed in parse results.
- Data Structure sample values will now include schema example values.
- Request and Response body examples will now respect the example values of a
schema.
## 0.19.1
### Enhancements
- When a schema uses `allOf` and doesn't provide a type hint at the schema
root, the `allOf` types are matched for object schemas. This allows the
following schema to work where before `type: object` was required at the
schema root at the same level as `allOf`:
```yaml
allOf:
- type: object
properties:
username:
type: string
- type: object
properties:
name:
type: string
```
### Bug Fixes
- When using `enum` in conjunction with `x-nullable` in a schema, this will now
result in the `null` value being present in schema if it isn't already.
## 0.19.0
### Enhancements
- Enumeration behaviour is now the same as API Elements 1.0 such that the
values that are fixed will now have a fixed type attribute.
## 0.18.4
### Enhancements
- Swagger `security-scheme` vendored extensions are now present in the parse
result.
### Bug Fixes
- Supports detecting Swagger documents which are JSON formatted with spaces
before the `:`. For example, the following document would not be matched to
this adapter: `{ "swagger" : "2.0" }`.
- When a parameter has no valid enumerations defined in an `enum`, we will now
discard the enumeration in the parse result. Previously the parser would create an
empty enumeration element from completely invalid enumerations in a Swagger
document which can cause issues further down in subsequent tooling and Minim
serialisation.
## 0.18.3
### Bug Fixes
- Swagger Schemas are now recursively translated from Swagger schema into JSON
Schema draft 4 in the resultant messageSchema of a parse result. This fixes
bugs where components such as `x-nullable`, `readOnly`, `externalDocs` etc
are not handled when found inside another schema as a sub-schema.
## 0.18.2
### Bug Fixes
- Fixes an issue where auth scheme elements are re-used multiple times in
a parse result which can cause exceptions when the parse result is frozen.
This is in the case where you have multiple consumes so multiple
request/response pairs are created for the action.
## 0.18.1
### Enhancements
- Allow `date` and `date-time` format support.
## 0.18.0
### Breaking
- Support for Node 4 was removed. Node 6 is the minimum supported version of
Node.
### Enhancements
- Adds support for the `x-nullable` schema extension. This allows adding `null`
as a type to a schema. This is an OpenAPI 3 feature ported to Swagger 2 as a
vendored extension.
[#112](https://github.com/apiaryio/fury-adapter-swagger/issues/112)
## 0.17.0
### Enhancements
- Optional object properties are now always present in generated JSON examples.
## 0.16.1
### Bug Fixes
- Allow parsing Swagger parameters of array type which do not have samples and
offer `items` which does not include a type.
- Coerce a resource `x-summary` value to a string if it is not already a
string. When a user enters an incorrect type such as boolean, number or
array. The title would become an incorrect type and can cause subsequent
tooling to fail.
## 0.16.0
### Enhancements
- Samples and Defaults of enum schema and parameters are now wrapped
in enum element.
## 0.15.2
### Enhancements
- File type parameters are now included instead of being ignored.
## 0.15.1
### Bug Fixes
- Data Structure generation was not including required typeAttribute for
required object properties.
## 0.15.0
### Enhancements
- Sample values are now generated for data structures of object and array types.
- Request/Response pairs are now generated from explicit examples, or the first
JSON produces content-type.
## 0.14.3
### Bug Fixes
- Generated multipart form-data example requests were missing the end of the
multi-part.
- `example` properties in Schema Object are not respected in data structure
generation.
## 0.14.2
### Bug Fixes
- Prevent throwing or attaching additional warning while handling a source YAML
document that produces an error while using the `generateSourceMap` flag.
There was a race condition where the `done` callback can be called twice as
we would call the callback with an error and `fury` would catch a raised
error and then return that error. This would also cause a state when parsing
an invalid YAML document would produce an error AND a warning in the returned
parse result.
## 0.14.1
### Enhancements
- Request example bodies are now generated for formData parameters while using
the `multipart/form-data` consumes content type.
## 0.14.0
### Bug Fixes
- Request and response pairs are now created for all combinations of produces,
and consumes content types. This includes multiple JSON content types which
we're previously discarded and non-JSON content types.
- `multipart/form-data` consumes type is no longer replaced by
`application/x-www-form-urlencoded` when formData parameters are provided.
[#96](https://github.com/apiaryio/fury-adapter-swagger/issues/96)
## 0.13.4
### Enhancements
- Added support for `externalDocs`.
- Parser will now give warning about unsupported collection formats in parameters.
## 0.13.3
### Bug Fixes
- Parameter default, example and enumerations values are now validated against
the parameter type. Invalid values will emit warnings and be discarded, this
resolves further problems when handling the invalid values.
- Data Structure generation will now support integer JSON Schema type.
## 0.13.2
### Bug Fixes
- HOST metadata was incorrectly included in an attribute called `meta`. The
attribute was renamed to `metadata` in API Elements 1.0.
- Fixes an issue where auth scheme elements are re-used multiple times in
a parse result which can cause exceptions when the parse result is frozen.
## 0.13.1
### Bug Fixes
- Handle array parameters which contain enumerations.
## 0.13.0
- Compatibility with [Minim 0.19](https://github.com/refractproject/minim/releases/tag/v0.19.0)
and [Fury 3.0.0-beta.4](https://github.com/apiaryio/fury.js/releases/tag/v3.0.0-beta.4).
### Enhancements
- Support `allOf` when generating data structures for objects
### Breaking
- Updated enum to match the new [format](https://github.com/apiaryio/api-elements/pull/28)
### Bug Fixes
- Add warning when x-example is not of error type when defined as array
## 0.12.1
### Enhancements
- Support `allOf` in object JSON Schemas when producing object data structure
elements.
## 0.12.0
- Updates to fury 3.0.0-beta.3 which supports Refract 1.0 serialisation
rules.
## 0.12.0-beta.3
- Updates to fury 3.0.0-beta.2.
### Bug Fixes
- Adds support for `csv` and `multi` parameter collectionFormat for query
parameters.
- Parameters which define both an example (`x-example`) and `items` schema will
now use the `x-example` value as the example.
- URI Template variables are now correctly escaped.
## 0.12.0-beta.2
### Bug Fixes
- Data Structure generation from JSON Schema handles array items which
contain empty values.
## 0.12.0-beta.1
### Enhancements
- Data Structure elements are now generated from JSON Schema found in examples.
## 0.11.1 (2017-04-25)
### Bug Fixes
- Updated yaml-js dependency to 0.1.5. This resolves problems with determining
source maps for Swagger documents that include multi-byte unicode characters
such as emoji.
## 0.11.0 (2017-04-11)
- Update fury to 3.0.0-beta.0
- Update minim to 0.15.0
- Update minim-parse-result to 0.4.0
## 0.10.0 (2017-03-30)
- Upgraded babel-runtime dependency to v6
- Drop support for node 0.12 and 0.10
## 0.9.13 (2017-02-07)
### Bug Fixes
- Handle inheritance for Path level Parameters
## 0.9.12 (2016-12-13)
### Bug Fixes
- Improve handling of default in parameters.
- Prevent a crash on invalid media types, such as `application/json;
invalid-component` and produce warnings for invalid media types.
## 0.9.11 (2016-11-25)
### Bug Fixes
- Fixes crashes on bad media types.
## 0.9.10 (2016-11-24)
### Bug Fixes
- Circular references in examples will now give a warning about not being supported yet.
## 0.9.9 (2016-11-15)
### Bug Fixes
- Generates JSON examples for JSON subtypes such as `application/hal+json`.
- Fixes a crash during sourcemap construction for some specific documents
## 0.9.8 (2016-10-31)
### Bug Fixes
- Prevents constructing large arrays and strings when generating a request or
response body from a JSON Schema where there is a large
`minItems`, `maxItems`, `minLength` or `maxLength`.
## 0.9.7 (2016-10-25)
### Bug Fixes
- Prevents dereferencing external assets such as local files.
## 0.9.5 (2016-09-01)
### Bug Fixes
- Improves error reporting in some cases when references are involved.
- Improves error reporting when the YAML document contains YAML syntax errors
to include source maps and the YAML error.
## 0.9.4 (2016-08-30)
## 0.9.3 (2016-08-30)
### Bug Fixes
- Added support to exclude extensions from operations
## 0.9.2 (2016-08-26)
### Enhancements
- Upgraded lodash dependency from 3.x.x to 4.x.x
## 0.9.1 (2016-07-27)
### Enhancements
- Added support for adding example values to parameters using `x-example`
## 0.9.0 (2016-07-27)
### Enhancements
- Added support for parameter property called x-example, which allows to specify
example values also for non-body parameters.
## 0.8.1 (2016-07-16)
### Enhancements
- The adapter is more asynchronous and thus, gives other events in the event
loop the ability to run while we're parsing the Swagger document.
## 0.8.0 (2016-07-01)
### Enhancements
- Added authentication support.
- Swagger vendor extensions are now exposes as API Element extensions.
- Response and Request bodies are generated from Schema whenever applicable.
- Accept and Content-type headers are generated based on produces and consumes keys whenever applicable.
- Sample values for non-body parameters are generated whenever applicable.
- Header parameters are appended to request/response header collection.
- Added `formData` support and appropirate request body generation.
### Bug Fixes
- Fixed metadata not being an array of Member Elements.
- Added source maps to resource.href, httpRequest.method, httpResponse.statusCode.
- Removed several unneeded source maps.
- Circular schema references will now give a warning about not being supported yet.
- Added fragment to uncaught error.
- Fixed bug with parameters sourcemaps when they are mixture of body and query parameters.
## 0.7.3 (2016-04-12)
- All exceptions thrown when converting swagger to refract will now be caught and returned as a proper error in parse result
## 0.7.2 (2016-02-18)
- Add an example for testing the module in the browser via TonicDev.
## 0.7.1 (2016-02-15)
- Swagger's `operationId` is now correctly interpreted as transition element's `id` instead of `relation`.
## 0.7.0 (2016-02-02)
- Swagger documents that do not validate against the JSON Schema for Swagger
will no longer be translated into Refract and instead expose errors for the
validation failures.
## 0.6.2 (2016-01-13)
- Bad JSON references (using `$ref`) are now returned as parse result
annotations that include source maps which point to the `$ref` line, making
debugging easier.
## 0.6.1 (2016-01-11)
- Fix handling of resource `href`, which could get overwritten while processing transitions and result in missing parameters in the URI template.
- Code refactoring
- Parsing is now handled by a class to more easily share state between various methods. This lays the framework for more refactoring and code cleanup.
- The parser shared state tracks the path of the component currently being parsed, which makes it easier to split pieces of the parser into separate methods.
- YAML AST lookup paths are now arrays of strings rather than strings of period-separated components, which made escaping very difficult.
- Rather than guessing the YAML type, the AST lookup now checks and handles it accordingly. Paths like `'foo.bar.0.baz'` would fail previously and now work (but are passed as `['foo', 'bar', '0', 'baz']`).
- Underscore is now replaced with Lodash for consistency with other modules.
## 0.6.0 (2015-12-14)
- Invalid YAML now returns error
## 0.5.3 (2015-12-11)
- Add source maps for YAML parse error annotations, which were previously missing.
## 0.5.2 (2015-12-10)
- Add support for `formData` parameters, which get converted into request data structures.
- Add source maps for `messageBodySchema` assets.
## 0.5.1 (2015-12-10)
- Do not encode JSON strings twice
- Support `x-summary` and `x-description` in Path Item Objects
## 0.5.0 (2015-12-08)
- Generate Swagger schema and spec validation annotations.
- Implement support for link relations in parser annotations.
- Encode dashes (`-`) in URI template parameters.
## 0.4.0 (2015-12-02)
- Implement support for parser annotations.
## 0.3.2 (2015-11-30)
- Implement support for source maps.
## 0.3.1 (2015-11-25)
- Fixes bug where URI templates appended empty query section.
- Fixes additional slashes in URLs when basePath ends with `/`.
## 0.3.0 (2015-11-18)
- Handle Swagger extensions (`x-*` fields).
- Support tags as resource groups when possible.
- Support hostname and basepath.
- Support request parameters when no response is given.
- Better support for HTTP headers.
- Add module for building URI templates from path and operation parameters.
## 0.2.0 (2015-11-17)
- Allow input to be either a loaded object or JSON/YAML string.
- Better JSON Schema reference handling via `json-schema-ref-parser` package.
- Do not set resource titles.
- Use `summary` instead of `operationId` for action titles.
- Set a relation value based on `operationId` for actions.
## 0.1.0 (2015-09-22)
- Initial release.