GitHub houses over 50 million designers working together to host and review code, handle projects, and build computer computer software together.
Scores of designers and organizations develop, ship, and keep their pc pc software on GitHub — the biggest and a lot of higher level development platform in the field.
OpenAPI-Specification / versions / 2.0.md
- Head to register T
- Head to line L
- Copy path
22 contributors
Users who’ve added for this file
(fka Swagger RESTful API Documentation Specification)
The key words “MUST”, “SHOULD NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “MUST NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in this document should be interpreted as described in RFC 2119.
The Swagger specification is certified beneath the Apache License, variation 2.0.
Swaggerв„ў is just a project utilized to spell it out and document RESTful APIs.
The Swagger specification defines a collection of files necessary to explain this kind of API. These files are able to be utilised by the Swagger-UI task to show the API and Swagger-Codegen to create customers in a variety of languages. Extra resources may also make use of the ensuing files, such as for example evaluation tools.
Path templating is the use of curly braces (<>) to mark a element of a path that is url changeable making use of course parameters.
Mime kind definitions are spread across a few resources. The mime type definitions ought to be in conformity with RFC 6838.
A few examples of feasible mime kind definitions:
HTTP Reputation Codes
The HTTP Status Codes are accustomed to suggest the status of this performed operation. The available status codes are described by RFC 7231 plus in the IANA reputation Code Registry.
The files explaining the API that is RESTful in utilizing the Swagger specification are represented as JSON objects and comply with the JSON standards. YAML, being a superset of JSON, can be utilized too to express a Swagger specification file.
For instance, if a field is thought to have a selection value, the JSON array representation will soon be utilized:
As the API is described JSON that is using it perhaps maybe perhaps not impose a JSON input/output towards the API it self.
All industry names within the specification are instance delicate.
The schema reveals two kinds of industries. Fixed industries, that have a announced title, and Patterned industries, which declare a regex pattern for the industry title. Patterned areas may have numerous occurrences so long as each includes a unique title.
The Swagger representation regarding the API is constructed of a solitary file. Nevertheless, elements of the definitions could be divided in to split files, in the discernment for the individual. This can be relevant for $ fields that are ref the specification the following through the JSON Schema definitions.
By meeting, the Swagger specification file is known as swagger.json .
Ancient information kinds when you look at the Swagger Specification depend on the kinds supported by the JSON-Schema Draft 4. versions are described utilising the Schema Object which will be a subset of JSON Schema Draft 4.
Yet another ancient information type “file” can be used because of the Parameter Object and also the Response item to create the parameter kind or the reaction to be a file.
Primitives have actually a modifier property format that is optional . Swagger utilizes a few understood platforms to more define the data finely type getting used. Nonetheless, the format home is an open sequence -valued property, and will have value to guide paperwork requirements. platforms such as “email” , “uuid” , etc., may be used despite the fact that they’re not defined by this specification. Kinds that aren’t associated with a format home follow their meaning through the JSON Schema (with the exception of file kind which can be defined above). The platforms defined by the Swagger Specification are:
Here is the root document item for the API specification. It combines just just exactly exactly what formerly had been the Resource Listing and API Declaration (version 1.2 and previous) together into one document.
The object provides metadata in regards to the API. The metadata can be utilized by the consumers if required, and may be presented when you look at the Swagger-UI for convenience.
Information Object Example:
Email address when it comes to uncovered API.
Contact Object Example:
Permit information for the uncovered API.
License Object Example:
Holds the general paths to your specific endpoints. The road is appended towards the basePath to be able to build the total Address. The Paths might be empty, as a result of ACL constraints.
Paths Object Example
Path Item Object
Defines the operations available on a path that is single. A Path Item can be empty, because of ACL constraints. The trail it self continues to be subjected to the paperwork audience however they will maybe perhaps perhaps perhaps perhaps not understand which operations and parameters can be obtained.
Path Item Object Example
</p>
Defines an individual api procedure on a course.
Procedure Object Example
External Documentation Object
Allows referencing a outside resource for extensive documents.
Outside Documentation Object Example
Defines an operation parameter that is single.
A unique parameter his comment is here is defined by a mixture of a title and location.
You can find five parameter that is possible.
- Course – Used together with Path Templating, where in actuality the parameter value is obviously area of the procedure’s Address. This doesn’t range from the host or base course regarding the API. As an example, in /items/
, the road parameter is itemId . - Query – Parameters which can be appended to your Address. For instance , the question parameter is id .
- Header – Customized headers which are anticipated within the demand.
- Body – The payload which is appended towards the HTTP demand. Since there can only just be one payload, there is only able to be one human body parameter. The title associated with the human body parameter doesn’t have influence on the parameter it self and it is useful for paperwork purposes just. Since Form parameters are into the payload, human body and type parameters cannot occur together for the exact same procedure.
- Form – utilized to explain the payload of a HTTP request whenever either , multipart/form-data or both are utilized once the type that is content of demand (in Swagger’s meaning, the consumes home of a procedure). This is actually the only parameter kind that enables you to deliver files, hence giving support to the file kind. Since kind parameters are delivered when you look at the payload, they can’t be announced along with a human body parameter for the exact same procedure. Type parameters have format that is different in the content-type utilized (for further details, consult):
- Like the structure of Query parameters but as a payload. For instance – both foo and club are form parameters. This really is ordinarily useful for easy parameters which are being transmitted.
- multipart/form-data – each parameter requires a part within the payload having a interior header. For instance, for the header Content-Disposition: form-data; name=”submit-name” the true title associated with the parameter is submit-name . This sort of type parameters is much more widely used for file transfers.
