OpenAPI-diff-ignore
Parse a OpenAPI-diff ignore file specifications(1.x). Can be use to integrate with OpenAPI-diff and customize your breaking changes.
If you think you have found a bug, please file an issue in the Github Issues.
Ignore Specification
Schema
In the following description, if a field is not explicitly REQUIRED or described with a MUST or SHALL, it can be considered OPTIONAL.
Fixed Fields
Field Name | Type | Description |
---|---|---|
extends | string |
Can be used to inherit a pre defined ignore file functionality. Provides metadata about basic ignore file for your custom API ignore. (Like -> “.default”) |
version | string |
REQUIRED. This string MUST be the semantic version number of the Ignore Specification version that the OpenAPI ignore document uses. The version field SHOULD be used by tooling specifications and clients to interpret the OpenAPI ignore document. |
info | string |
Provides metadata about general info for the API ignore. The metadata MAY be used by tooling as required. |
project | string |
Provides metadata about the Project using the ignore file. The metadata MAY be used by tooling as required. |
paths | Paths Object | The available paths and operations for the API that needed to be ignored. |
Paths Object
Holds the relative paths to the individual endpoints and their operations.
Patterned Fields
Field Pattern | Type | Description |
---|---|---|
/{path} | Path Item Object | A relative path to an individual endpoint. The field name MUST begin with a slash. Wildcard is allowed. When matching URLs. In case of ambiguous matching, it’s up to the tooling to decide the execution order. |
Path Wildcard Matching
Assuming the following paths, the concrete definition, /pets/mine
, will be matched if used:
/pets/** # will match and also match all pets endpoints
/** # will match and also will match all endpoints
NOTICE! When using wildcards all endpoints matching the wildcard will apply the ignore specified.
Paths Object Example
paths:
/pet/**, /store/**: # this path will match any 'pet' or 'store' endpoint
get:
response:
200:
new: true
parameters:
- username
- password
post:
request:
content:
application/json, application/octet-stream: $
response:
200:
new: true
content:
application/json:
schema:
properties:
- petId
- quantity
- shipDate
- complete
security:
petstore_auth:
- 'write:pets'
- 'read:pets'
/user/login: # this path will match only '/user/login' endpoint.
post: $
Path Item Object
Describes the operations available on a single path. A Path Item MAY be empty, due to ACL constraints. The path itself is still exposed to the documentation viewer but they will not know which operations and parameters are available.
Fixed Fields
Field Name | Type | Description |
---|---|---|
get | Operation Object | A definition of a GET operation on this path. |
put | Operation Object | A definition of a PUT operation on this path. |
post | Operation Object | A definition of a POST operation on this path. |
delete | Operation Object | A definition of a DELETE operation on this path. |
options | Operation Object | A definition of a OPTIONS operation on this path. |
head | Operation Object | A definition of a HEAD operation on this path. |
patch | Operation Object | A definition of a PATCH operation on this path. |
trace | Operation Object | A definition of a TRACE operation on this path. |
Path Item Object Example
post:
request:
content:
application/json, application/octet-stream: $
response:
200:
new: true
content:
application/json:
schema:
properties:
- petId
- quantity
- shipDate
- complete
security:
petstore_auth:
- 'write:pets'
- 'read:pets'
put: $
delete: $
Operation Object
Describes a single API ignore operation on a path.
Fixed Fields
Field Name | Type | Description |
---|---|---|
security | Security Object | A list of security requirements that are going to be ignored. |
parameters | Parameter Object | A list of parameters that are going to be ignored. |
request | Request Object | The request body applicable for this operation. can specify ignore for content-type. |
response | Response Object | The list of possible response statuses that are going to be ignored. |
Operation Object Example
request:
content:
application/json, application/octet-stream: $
parameters:
- username
- password
response:
200:
new: true
content:
application/json:
schema:
properties:
- petId
- quantity
- shipDate
- complete
security:
petstore_auth:
- 'write:pets'
- 'read:pets'
Security Object
Describes a security requirements that needed to be ignored.
Fixed Fields
Field Name | Type | Description —|:—:|— {schema} | Map<String, List> | A map of security requirements that are going to be ignored.
Security Object Example
security:
petstore_auth:
- 'write:pets'
- 'read:pets'
api_key:
- 'read:users'
Documentation
More information can be found on Docs.
Where can I get the latest release?
You can download release source from our release page.
Contributing
If you are interested in the development of OpenAPI-diff-ignore, please consult the documentation first and afterwards you are welcome to join the developers mailing list to ask question or discuss new ideas / features / bugs etc.
Take a look into the contribution guidelines.
Quick Build
If you want to bootstrap openapi-diff-ignore, you’ll need:
- Java 1.8+
- Maven 3.x.x or later
- Run Maven, specifying a location into which the completed Maven distro should be installed:
./mvnw clean package