Formats such as "email", "uuid", etc., can be used even though they are not defined by this specification. However, the format property is an open string-valued property, and can have any value to support documentation needs. Swagger uses several known formats to more finely define the data type being used. Primitives have an optional modifier property format. Models are described using the Schema Object which is a subset of JSON Schema Draft 4.Īn additional primitive data type "file" is used by the Parameter Object and the Response Object to set the parameter type or the response as being a file. Primitive data types in the Swagger Specification are based on the types supported by the JSON-Schema Draft 4. This is applicable for $ref fields in the specification as follows from the JSON Schema definitions.īy convention, the Swagger specification file is named swagger.json. However, parts of the definitions can be split into separate files, at the discretion of the user. The Swagger representation of the API is made of a single file. Patterned fields can have multiple occurrences as long as each has a unique name. Fixed fields, which have a declared name, and Patterned fields, which declare a regex pattern for the field name. While the API is described using JSON it does not impose a JSON input/output to the API itself.Īll field names in the specification are case sensitive. Some examples of possible mime type definitions: The mime type definitions should be in compliance with RFC 6838. Mime type definitions are spread across several resources.
Path templating refers to the usage of curly braces () to mark a section of a URL path as replaceable using path parameters. Revision History Versionįirst release of the Swagger Specification Additional utilities can also take advantage of the resulting files, such as testing tools. These files can then be used by the Swagger-UI project to display the API and Swagger-Codegen to generate clients in various languages. The Swagger specification defines a set of files required to describe such an API. Swagger™ is a project used to describe and document RESTful APIs. The Swagger specification is licensed under The Apache License, Version 2.0. The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119. OpenAPI Specification (fka Swagger RESTful API Documentation Specification) Version 2.0