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