The OpenAPI Specification Repository

Overview

The OpenAPI Specification

Build Status Issue triagers

The OpenAPI Specification is a community-driven open specification within the OpenAPI Initiative, a Linux Foundation Collaborative Project.

The OpenAPI Specification (OAS) defines a standard, programming language-agnostic interface description for HTTP APIs, which allows both humans and computers to discover and understand the capabilities of a service without requiring access to source code, additional documentation, or inspection of network traffic. When properly defined via OpenAPI, a consumer can understand and interact with the remote service with a minimal amount of implementation logic. Similar to what interface descriptions have done for lower-level programming, the OpenAPI Specification removes guesswork in calling a service.

Use cases for machine-readable API definition documents include, but are not limited to: interactive documentation; code generation for documentation, clients, and servers; and automation of test cases. OpenAPI documents describe an APIs services and are represented in either YAML or JSON formats. These documents may either be produced and served statically or be generated dynamically from an application.

The OpenAPI Specification does not require rewriting existing APIs. It does not require binding any software to a service – the service being described may not even be owned by the creator of its description. It does, however, require the capabilities of the service be described in the structure of the OpenAPI Specification. Not all services can be described by OpenAPI – this specification is not intended to cover every possible style of HTTP APIs, but does include support for REST APIs. The OpenAPI Specification does not mandate a specific development process such as design-first or code-first. It does facilitate either technique by establishing clear interactions with a HTTP API.

This GitHub project is the starting point for OpenAPI. Here you will find the information you need about the OpenAPI Specification, simple examples of what it looks like, and some general information regarding the project.

Current Version - 3.1.0

The current version of the OpenAPI specification is OpenAPI Specification 3.1.0.

Previous Versions

This repository also contains all previous versions.

Each folder in this repository, such as examples and schemas, should contain folders pertaining to the current and previous versions of the specification.

See It in Action

If you just want to see it work, check out the list of current examples.

Tools and Libraries

Looking to see how you can create your own OpenAPI definition, present it, or otherwise use it? Check out the growing list of implementations.

Participation

The current process for development of the OpenAPI Specification is described in Development Guidelines. Development of the next version of the OpenAPI Specification is guided by the Technical Steering Committee (TSC). This group of committers bring their API expertise, incorporate feedback from the community, and expand the group of committers as appropriate. All development activity on the future specification will be performed as features and merged into this branch. Upon release of the future specification, this branch will be merged to main.

The TSC holds weekly web conferences to review open pull requests and discuss open issues related to the evolving OpenAPI Specification. Participation in weekly calls and scheduled working sessions is open to the community. You can view the TSC calendar online. Look for the "Subscribe to Calendar" button for instructions on subscribing.

The OpenAPI Initiative encourages participation from individuals and companies alike. If you want to participate in the evolution of the OpenAPI Specification, consider taking the following actions:

  • Review the current specification. The human-readable markdown file is the source of truth for the specification.
  • Review the development process so you understand how the spec is evolving.
  • Check the issues and pull requests to see if someone has already documented your idea or feedback on the specification. You can follow an existing conversation by subscribing to the existing issue or PR.
  • Subscribe to an open issue a day (or a week) in your inbox via CodeTriage.com.
  • Create an issue to describe a new concern. If possible, propose a solution.

Not all feedback can be accommodated and there may be solid arguments for or against a change being appropriate for the specification.

Licensing

See: License (Apache-2.0)

Analytics

Comments
  • Make schema object compatible with JSON Schema draft4

    Make schema object compatible with JSON Schema draft4

    According to spec swagger inside schema object support only limited subset of JSON Schema draft4 and extend it with custom keywords.

    This isssue was hidden, before 68c6777dc5eba98dc1eb791983693f089e9d3366 commit any swagger model with arbitrary JSON schema was valid(against Swagger schema).

    These create a problem, because in reality most of tools use standard JSON schema validators(for e.g. swagger-tools use z-schema, swagger-express-middleware use tv4). And I didn't found any true Swagger 2.0 validator in the wild.

    Another problem is that you can't reference existing schemes inside your swagger files. It became real problem, if you want to use some standard scheme or simply reuse your existing validation scheme. For example if you make API that return swagger definitions and want to reuse existing schema, you can't simply use '$ref' or even copy-paste it.

    Finally it brake compatibility with all tooling around JSON Schema not only validators but also documentation generators, UI form generators, etc.

    On technical side, this is list of Draft4 keywords doesn't supported by Swagger: id, $schema, additionalItems, definitions, patternProperties, dependencies, anyOf, oneOf, not.

    Also there are "discriminator" and "readOnly" Swagger specific keywords that don't supported by JSON Schema validators. "discriminator" could be safely substitute with "oneOf" construction, as for "readOnly" same behaviour could be achieved by using "allOf" with "write part" and "read-only part". My proposal it either to remove these keywords or make them optional to support.

    Also there are "safe" custom keywords namely "example" and "externalDocs", they shouldn't cause any serious trouble, but should be submitted as requests for Draft5 to ensure future compatibility.

    Last keyword is "xml", I didn't make any research about it, so I can't say if it used in any Swagger related project or if it brake JSON schema compatibility.

    OpenAPI.Next Proposal 
    opened by IvanGoncharov 131
  • Proposal: x-oas-draft-alternativeSchemas

    Proposal: x-oas-draft-alternativeSchemas

    A long standing request has been to add support for alternate schemas. See #764 #1443

    There are many concerns about the effect this will have on the tooling ecosystem, however, there is also a strong desire from the community to support both more recent versions of JSON Schema and other formats such as XSD Schema, Protobuf Schema.

    Instead of simply adding this feature to the specification and hoping that tooling vendors will implement it. I propose we use the draft feature (PR #1531 ) process to validate the value and feasibility of this feature.

    openapi: 3.0.2
    info:
      title: A sample using real JSON Schema and xsd
      version: 1.0.0
    paths:
      /:
        get:
          responses:
            '200':
              description: Ok
              content:
                application/json:
                  x-oas-draft-alternate-schema:
                    type: json-schema
                    externalValue: ./rootschema.json
                application/xml:
                  x-oas-draft-alternate-schema:
                    type: xml-schema
                    externalValue: ./rootschema.xsd
    
    • The property is called alternate-schema because it can be used in instead of, or in addition to the OAS Schema object. If both are present then both schemas must be respected.
    • The type field is required and must match one of the values identified in an alternate schema registry which will be created as part of this proposal. The alternate schema registry will provide a link to a specification for the schema file.
    • It is recommended that tools provide users with warnings when they encounter an alternate schema type that they do not support. Tools should not fail to process a description, unless the schema is essential to the operation. Ideally they should continue as if the alternate-schema is not present in a form of graceful degradation.
    • The externalValue property is required and must be a relative or absolute URL.
    • The alternate-schema property can be used anywhere the schema property can be used.
    draft-feature draft:pilot 
    opened by darrelmiller 119
  • add

    add "null value support" in spec?

    Per https://github.com/swagger-api/swagger-core/issues/459 there are cases where passing null is important. For example:

    [ null ]
    

    will be quite different than []. See if this can be an option

    OpenAPI.Next Proposal 
    opened by fehguy 117
  • Support for multiple request/response models based on headers

    Support for multiple request/response models based on headers

    I guess this is a 2.0+ request as 2.0 is already "released".

    Basically, there is currently no way to express a single path which may have different request/response formats based on additional criteria, namely headers. two possible scenarios:

    1. An API which supports both xml and json, but the models for each format are different enough that they cannot be expressed via a single json schema w/ xml annotations (even if the xml format is expressible using the xml annotations).
    2. An API which supports versioning the representation via the media-type. e.g. application/my+v1 returns a json model which is sufficiently different from the application/my+v2 model such that i cannot describe them both using one unified model.

    If supporting different responses for arbitrary headers is too big of a change, just supporting multiple media-types (for request and response) would be sufficient for the cases described here.

    OpenAPI.Next Proposal Sub Issue 
    opened by jahlborn 100
  • Extra JSON Reference properties ignored - reduces reusability of references

    Extra JSON Reference properties ignored - reduces reusability of references

    Hi everyone.

    I feel that the ignoring of extra properties when using JSON References goes against the goal of reusability.

    Take this example from a fictional Swagger contract:

    {
        addresses: [
            "homeAddress": {
                "description": "The premises at which electricity is provided.",
                "$ref": "#/definitions/Address"
            },
            "invoiceAddress": {
                "description": "The billing address - must be where the customer's credit card is registered.",
                "$ref": "#/definitions/Address"
            }
        ]
    }
    

    The "description" properties help to distinguish between the two uses of the "Address" Reference. Of course you could argue that better naming of the "homeAddress" and "invoiceAddress" properties could achieve this, but we are not always in control of property names in our data models and sometimes you need a more verbose description.

    The Swagger editor (http://editor.swagger.io/#/) is an example of an application that could be improved by removing this limitation.

    Is this something that has been raised previously? Please see here for a discussion on the Swagger Google Group: https://groups.google.com/forum/#!topic/swagger-swaggersocket/ewgimdO2cOI

    OpenAPI.Next Proposal Sub Issue $ref 
    opened by JimJafar 87
  • Allow for multiple response schemas for each response code

    Allow for multiple response schemas for each response code

    Example

      responses:
        200:
          description: An array of events
          schema:
            type: array
            items:
              $ref: '#/definitions/Event'
        200:
          description: |
            An array of flattened events. This is the response
            object when singleEvents is True.
          schema:
            type: array
            items:
              $ref: '#/definitions/EventFlat'
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Error'
    
    opened by aroemen 81
  • Allow documenting HATEOAS APIs (pathless operation / interface / URI class / operation type)

    Allow documenting HATEOAS APIs (pathless operation / interface / URI class / operation type)

    TLDR

    (added after some discussion)

    • "interfaces" (like path items, just without path parameters, and not linked to a path template)
    • a path item can refer to an interface (which is implemented), possibly adding path parameters to it
    • a string property (containing an URI) in a schema can refer to an interface (which means the consumer can know which operations can be used on this URI)

    Background / Current Situation

    I work at a company where our Restful API Guidelines prescribe both "document your API using OpenAPI" and "Use HATEOAS" ("Hypertext as the Engine of Application State", one of the core principles of REST).

    Unfortunately both do not work together nicely:

    • Swagger/OpenAPI 2.0's model is "we have paths which can be distinguished in some way, and describe the operations on those paths" (including their data format).
    • The HATEOAS model is "The client gets a result which might contain links to other resources, and can decide to follow them, no matter which URI format they have".

    Currently the intersection between both is "have links in your result, but just to URIs which are also described as paths in your Swagger definition, and describe in descriptions what kind of URIs you can expect".

    Ideas

    A core point of HATEOAS are media types and link relations. An API definition should mainly be a description of the media types and what operations they imply for links included in them. (Paraphrased from a blogpost of Roy Fielding.)

    Media type definitions are analogous to what OpenAPI's definitions are currently, might even be an extension of that. For models with a property of type string, format uri we can then additionally refer to the URI class of that URI.

    A URI class is defined analogously to the current path definitions, but with some name to be used in model definitions. The URI class defines what operations are possible on an URI, which parameters are allowed/needed (no path parameters, I guess), and what can be expected in return. (The URI class is not a property of the URI itself, but of its usage in a specific place. The same URI could appear with multiple URI classes.)

    I'm not yet sure how link relations can come into this – I guess we might need a way to define the URI class depending on link relation or similar.

    A client needs just some initial "bookmark URI" (so a single path definition might be fine), and then can take a link (with a given URI class) and use the operation behind the URI class to do what it wants to do. The format of the second URI doesn't matter anymore to the client – it can even have a different domain name than the bookmark one. But still everything can be strongly typed if wanted.

    OpenAPI.Next Proposal Sub Issue 
    opened by ePaul 72
  • JSON Schema for the OpenAPI 3.0 Specification

    JSON Schema for the OpenAPI 3.0 Specification

    It looks like we don't yet have a JSON Schema to describe the OpenAPI 3.0 spec. The schemas folder has 1.2 and 2.0 subfolders, but nothing for 3.0 yet.

    We'd like to contribute to this. Is anyone working on a JSON Schema for the 3.0 spec yet?

    opened by tedepstein 68
  • Update Schema Objects to JSON Schema Draft 2019-09

    Update Schema Objects to JSON Schema Draft 2019-09

    Fixes #333 Fixes #397 Fixes #470 Fixes #1026 Fixes #1238 Fixes #1313 Fixes #1368 Fixes #1389 Fixes #1494 Fixes #1523 Fixes #1666 Fixes #1719 Fixes #1766 Fixes #1869 Fixes #1985

    Checklist items from #1766 so we can close.

    • [x] @handrews "We should probably make sure none of the formats added in the newer draft conflict with the ones OpenAPI defines."
    • [x] @handrews "At most you might want to check if we have any slight incompatibilities for readOnly and writeOnly which were moved/added to the validation spec in [Draft 07]"

    Picking up from where https://github.com/OAI/OpenAPI-Specification/pull/1766 left off, this PR is helping OpenAPI v3.1 make a non-breaking change, to catch up with JSON Schema's latest draft.

    Instead of OpenAPI continuing to confuse everyone by being a JSON Schema draft 05 sub-set, and a super-set, with some notable differences to watch out for, it will now be a JSON Schema draft 2019-09 superset. More info on that here.

    The goal here is to help people write pure JSON Schema for their data model if they want to, or write OpenAPI-flavoured JSON Schema if they want to, but we are closing the gaps on what these two things mean. The list of differences is now tiny, only 4 extra keywords, with 2 notes about how exlusiveMinimum and exclusiveMaximum can be used in two ways (in order to maintain BC with OpenAPI v3.0).

    Alternative Solutions

    Alternative Schemas are a big topic which needs more work to be done. We should address the JSON Schema divergence issue to make the v3.x branch a happy place to be, and follow up with Alternative Schemas for v3.2 or v4.0, so our XML using friends can play with XML Schema, and all the other good things.

    Risks

    There are concerns that tooling vendors who work with static languages will have a hard time adding some of JSON Schemas newer more dynamic features. I understand this in theory, but most of JSON Schema's new features like if/then/else, and the old "type can be an array" issue, are just sugar for allOf/anyOf/oneOf, as can be seen in wework/json-schema-to-openapi-schema.

    Seeing as allOf, anyOf, oneOf already exist in OpenAPI v3.0, whatever tooling vendors are doing to support that, should be done to support these keywords. Other new things like const are just an enum of 1.

    Nothing should be that scary, yet people seem scared, but I think we can overcome in. We need to. JSON is a dynamic format, a property can contain a string one minute, and an object another, and this is pretty common practice for those using evolution. You might start out with a simple string, then decide you need more information and offer an object, deprecating the old way of doing things, and folks move over to use the object. This was an issue for reading JSON in Go for a while, then better JSON tooling came out and its not an issue.

    OpenAPI tooling should be able to deal with this too. For example, ReDoc is an awesome open-source documentation generator, and it has no trouble at all with showing oneOf:

    Screen Shot 2019-07-18 at 17 19 32 Screen Shot 2019-07-18 at 17 19 35

    The argument I keep hearing is "tooling vendors are complaining about anyOf, allOf, oneOf, because it's hard, so lets not add any more keywords... Meh? Which is the priority here, making lives slightly easier for the tooling vendors by not adding new features, or making lives substantially less confusing for all the users of all the OpenAPI tools by letting them not have to unpack the differences between OpenAPI and JSON Schema? I lose 10% of every day helping people navigate this mess on APIs You Won't Hate, and I'm a tooling vendor at Stoplight.io. I'd rather have a few more complex keywords to figure out for the tooling, than have all the users of that tooling be constantly confused about which keywords they can use when, and how to convert from one to the other because different tools need OpenAPI or JSON Schema.

    Anyhow, the tools that support advanced features will end up being more popular than the tools which do not. 🤷‍♂️

    Life for tooling vendors trying to add these new keywords can be simplified in a few ways:

    • Provide guidance in the form of blog posts (I got this)
    • Common tooling (Stoplight got this for JS)
    • JSON Schema tools can now be used directly, instead of building OpenAPI-based tooling which is similar then tweaking it... 🤦‍♂

    I'd like to dig into this fear of adopting actual JSON Schema further on the OpenAPI slack, so please swing by and throw examples at me. I have heard vague concerns about patternProperties, but would love to sink my teeth into concrete examples.

    opened by philsturgeon 63
  • Add support for Matrix type parameters

    Add support for Matrix type parameters

    Matrix type parameters are not fully supported by Swagger. Would be great to have them supported. See following google groups discussion on this topic with concrete example and a bunch of links about what matrix parameters are: https://groups.google.com/forum/#!topic/swagger-swaggersocket/lnQOLOLh3MI

    Thanks for great product! Greetings from Ireland

    OpenAPI.Next Proposal Sub Issue 
    opened by uralovs 52
  • Support for Either

    Support for Either

    hi.

    Would like to be able present a type of Either[Dog,Cat] (or in clojure (either Dog, Cat, Moose) in the Spec. Quite common construct in the FP land. Would be like a enum, but with values of any type.

    Currently such a thing could be presented as a complex type with optional fields for all the value => at least the swagger-ui would be able to generate sample models (with all possible alternatives in place) for it. Not perfect, but ~works. Requires also special coercion in the server side to map back into Either.

    http://www.scala-lang.org/api/2.11.0/index.html#scala.util.Either

    https://github.com/Prismatic/schema/blob/master/test/cljx/schema/core_test.cljx#L194-L203

    OpenAPI.Next Proposal Sub Issue 
    opened by ikitommi 50
  • Open Community (TDC) Meeting, Thursday 05 January 2023

    Open Community (TDC) Meeting, Thursday 05 January 2023

    NOTE: This meeting is on Thursday at 9am - 10am PT

    Zoom Meeting link: https://zoom.us/j/975841675. Dial-in passcode: 763054 - Code-of-Conduct

    In order to give some more visibility into the topics we cover in the TDC meetings here is the planned agenda for the next meeting. Hopefully this will allow people to plan to attend meetings for topics that they have an interest in. And for folks who cannot attend they can comment on this issue prior to the meeting. Feel free to suggest other potential agenda topics.

    Please submit comments below for topics or proposals that you wish to present in the TDC meeting

    F10B5460-B4B3-4463-9CDE-C7F782202EA9

    The agenda backlog is currently maintained in issue #2482

    | Topic | Owner | Decision/NextStep | |-------|---------|---------|
    | | | | Reports from Special Interest Groups | TDC | | AOB (see below) | TDC | | New issues / PRs labelled review | @OAI/triage | | New issues without response yet | @OAI/triage | |

    /cc @OAI/tsc Please suggest items for inclusion

    Housekeeping 
    opened by github-actions[bot] 0
  • Support for CBOR

    Support for CBOR

    I have after almost a decade with JSON, decided to use CBOR as the foundation for new designs (except for browser-based applications where the JavaScript/JSON combo still makes sense).

    The rationale is here: https://github.com/cyberphone/cbor-everywhere

    opened by cyberphone 0
  • Add new extension namespace registry

    Add new extension namespace registry

    In order to encourage the creation and registration of extensions in a central registry, this PR proposes creating a new namespace registry for extensions so that OpenAPI users can reserve an extension prefix for their organization to ensure uniqueness.

    opened by darrelmiller 1
  • Proposal: Promote date, time, and datetime to `type` so `format` becomes usable for them

    Proposal: Promote date, time, and datetime to `type` so `format` becomes usable for them

    One shortcoming of the type and format options relates to dates and times. Currently, I need to specify type: string and a format of either date, datetime, or time. That's great that we can specify those values, but there is nothing that allows me to specify to my API users what date or time format we use. Is it a unix timestamp, or ISO 8601, or MySQL format, or....? Are timestamps included? Do we cut off times at the minute, second, millisecond?

    Every modern language has a whole library for dealing with the complexities of this because it's not trivial. But, in OpenAPI, all I can do is say it's a date, and it's up to you to figure out how it's formatted. I can provide an example, but that doesn't help much with validation and tooling. My best option is to stick a pattern in there, repeat it for every date in my app, and hope users recognize the regex as "Oh, that's ISO 8601."

    I'd propose that date, datetime and time be promoted from formats to types in their own right, such that format becomes viable. Common formats can be provided for in the same way that formats for things like email and uuid are today, and for anything not covered by one of those constants, a format string similar to what language libraries use could be employed. This could then be supported by tooling for more flexible validation.

    Examples:

    type: datetime
    format: iso8601
    
    type: datetime
    format: "H:i:s A F j, Y"
    
    opened by mattholden 2
  • Proposal: Default options in discriminators

    Proposal: Default options in discriminators

    I have the following use case I'd like to solve:

    type: object
    description: Settings for a country
    allOf:
       - type: object
          properties:
            country_code:
                type: string
                description: ISO 3166 country code
                enum: AD, AE, AF, AG .... ZW
            common_field:
                type: string
                description: Something all countries have
    discriminator:
       description: Adds extra fields we need depending on country 
       propertyName: country_code
       mapping: 
           CA: #/CountryCA
           MX: #/CountryMX
           US: #/CountryGeneric
           DE: #/CountryGeneric
           ES: #/CountryGeneric
           # insert many more country definitions here that go to CountryGeneric
    

    This can be made to work, but I would have to have all 200+ countries in the mapping object, each pointing to a reference of an object, and this is really cumbersome. I'd really love to be able to do this, treating the discriminator almost like a switch statement:

    discriminator:
       description: Adds extra fields we need depending on country 
       propertyName: country_code
       mapping: 
           CA: #/CountryCA
           MX: #/CountryMX
       default: #/CountryGeneric
    
    opened by mattholden 1
  • Open Community (TDC) Meeting, Thursday 29 December 2022 (Cancelled for the holidays)

    Open Community (TDC) Meeting, Thursday 29 December 2022 (Cancelled for the holidays)

    NOTE: This meeting is on Thursday at 9am - 10am PT

    Zoom Meeting link: https://zoom.us/j/975841675. Dial-in passcode: 763054 - Code-of-Conduct

    In order to give some more visibility into the topics we cover in the TDC meetings here is the planned agenda for the next meeting. Hopefully this will allow people to plan to attend meetings for topics that they have an interest in. And for folks who cannot attend they can comment on this issue prior to the meeting. Feel free to suggest other potential agenda topics.

    Please submit comments below for topics or proposals that you wish to present in the TDC meeting

    F10B5460-B4B3-4463-9CDE-C7F782202EA9

    The agenda backlog is currently maintained in issue #2482

    | Topic | Owner | Decision/NextStep | |-------|---------|---------|
    | | | | Reports from Special Interest Groups | TDC | | AOB (see below) | TDC | | New issues / PRs labelled review | @OAI/triage | | New issues without response yet | @OAI/triage | |

    /cc @OAI/tsc Please suggest items for inclusion

    Housekeeping 
    opened by github-actions[bot] 0
Releases(3.1.0)
  • 3.1.0(Feb 16, 2021)

    The OAI is pleased to announce the official release of the OpenAPI Specification 3.1.0!

    Changelog

    See 3.1.0-rc1 for previous changes in 3.1.0, including the explanation of why there are breaking changes.

    Additions

    • Added the jsonSchemaDialect top-level field to allow the definition of a default $schema value for Schema Objects.

    Updates

    • Updated some links to more accurate locations.
    • Updates JSON Schema support to the latest 2020-12 draft.
    • Revamped relative reference resolution under both URIs and URLs.
    • Reworked file upload description to take into account new JSON Schema capabilities. This contains breaking changes.
    • Both x-oai- and x-oas- prefixes for Specification Extensions are now reserved to be defined by the OpenAPI Initiative.

    Clarifications

    • Path parameter values cannot contain the unescaped characters /, ? or #.
    • Further explanation of where Reference Object and JSON Schema's reference should be used.
    • Unified wording when values are URLs/URIs.
    • Reworded Path Item's $ref to take into account reference and component changes.
    • Fixed some examples.
    • Minor text changes to improve consistency and readability.
    • The description of the Reference Object has been updated to further clarify its behavior.
    • Further updated Schema Object's description to take into account the latest draft, and the default use of https://spec.openapis.org/oas/3.1/dialect/base as the default OAS dialect.
    • Reworded "Schema Vocabularies" to "Schema dialects"
    Source code(tar.gz)
    Source code(zip)
  • 3.1.0-rc1(Oct 9, 2020)

    Changelog

    See 3.1.0-rc0 for previous changes in 3.1.0, including the explanation of why there are breaking changes.

    Breaking changes

    • Server Variable's enum now MUST not be empty (changed from SHOULD).
    • Server Variable's default now MUST exist in the enum values, if such values are defined (changed from SHOULD).
    • responses are no longer required to be defined under the Operation Object.

    Clarifications

    • It is now clarified when path template expression may not have a corresponding path parameter.
    • Data types (and just primitive data types) now correspond to JSON Schema.
    • Various cosmetic fixes.
    • A new section was added to address how to handle the $schema keyword (implicitly and explicitly).
    Source code(tar.gz)
    Source code(zip)
  • 3.1.0-rc0(Jun 18, 2020)

    Changelog

    As part of this release, we have decided to not follow SemVer anymore, and as such introduce breaking changes. These changes are documented as part of the release notes.

    Additions

    • Introduced a new top-level field - webhooks. This allows describing out-of-band webhooks that are available as part of the API.
    • The Info Object has a new summary field.
    • The License Object now has a new identifier field for SPDX licenses.
    • Components Object now has a new entry pathItems, to allow for reusable Path Item Objects to be defined within a valid OpenAPI document.

    Extended Functionality

    • Updated primitive types to be based on JSON Schema Specification Draft 2019-09. This now includes type null.
    • Lifted the restriction of allowing Request Body only in HTTP methods where the HTTP 1.1 specification RFC7231 has explicitly defined semantics for. While allowed in other methods, it is not recommended.
    • Added support to object type for spaceDelimited and pipeDelimited style values.
    • The Encoding Object now supports style, explode and allowReserved for multipart/form-data media type as well.
    • To enable better webhooks support, expressions in the Callback Object can now also reference Path Item Objects.
    • When using the Reference Object, summary and description fields can now be overridden.
    • The Schema Object is now fully compliant with JSON Schema draft 2019-09 (see JSON Schema Core and JSON Schema Validation). See also, Breaking Changes
    • The Discriminator Object can now be extended with Specification Extensions.
    • Added support for mutual TLS (mutualTLS) as a security scheme.
    • Used security requirements can now define an array of roles that are required for execution (and not only scopes for OAuth 2.0 security schemes).

    Changes

    • An OpenAPI Document now requires at least one of paths, components or webhooks to exist at the top level. While previous versions required paths, now a valid OpenAPI Document can describe only webhooks, or even only reusable components. Thus, an OpenAPI Document no longer necessarily describes an API.
    • Anywhere in the 3.0.0 Specification that had a type of Schema Object | Reference Object has been replaced to be Schema Object only. With the move to full JSON Schema support, $ref is inherently part of the Schema Object and has its own defined behavior.
    • Extensions prefixed with x-oas- are now reserved for the OpenAPI Initiative.
    • format is now not validated by default.

    Breaking changes

    • The specification versioning no longer follows SemVer.
    • The nullable keyword has been removed from the Schema Object (null can be used as a type value).
    • exclusiveMaximum and exclusiveMinimum cannot accept boolean values (following JSON Schema).
    • Due to the compliance with JSON Schema, there is no longer interaction between required and readOnly/writeOnly in relation to requests and responses.
    • format (whether byte, binary, or base64) is no longer used to describe file payloads. As part of JSON Schema compliance, now contentEncoding and contentMediaType can be used for such specification.

    Clarifications

    • Reworded the definition of OpenAPI Document to reflect that a document no longer must describe paths, but can describe either paths, webhooks, components or any combination of them.
    • Dropped the term RESTful APIs in favor of HTTP APIs
    • Resolution of relative references has been redefined and clarified. Note there's a difference in resolution between Schema Object References and all others.
    • Modification of examples to improve them and provide context for new fields/objects.
    Source code(tar.gz)
    Source code(zip)
  • 3.0.3(Feb 21, 2020)

    OAS 3.0.3 Change Log

    The OAI is pleased to announce the official release of the OpenAPI Specification 3.0.3!

    As a patch release, the following changes were made to improve the specification in terms of readability and accuracy. None of these modifications change the behavior of the spec.

    • Clarified how Path Templating works.
    • Clarified the meaning of Semantic Versioning as it applies to the OpenAPI Specification (note, this is the openapi field, not the version field).
    • Changed some hyperlinks from http to https.
    • Clarified add the notion of optional security on operations.
    • Added an explanation that the Server Variable Object's enum should not be empty. This is not a breaking change but should be considered as guidance for a more explicit restriction in the next major version.
    • Clarified paths under the Paths Object should start with a forward slash.
    • Clarified Path Item Object's $ref behavior with sibling fields.
    • Fixed a few examples.
    • Clarified the map structure of callbacks under the Operation Object.
    • Clarified how path parameters are being matched.
    • Clarified example/examples value(s) in the Parameter Object.
    • Fixed example for pipeDelimited object value.
    • Fixed Callback Object description.
    • Clarified Link Object's operationDef's description.
    • Improved ABNF for Runtime Expressions.
    • Clarified valid regex for pattern under Schema Object.
    • Clarified the behavior of nullable under Schema Object.
    • Fixed names of OAuth2 flows in the description of Security Scheme Object.
    • Improved description of Security Filtering section.
    Source code(tar.gz)
    Source code(zip)
  • 3.0.2(Oct 8, 2018)

    OAS 3.0.2 Change Log

    The OAI is pleased to announce the official release of the OpenAPI Specification 3.0.2!

    As a patch release, the following changes were made to improve the specification in terms of readability and accuracy. None of these modifications change the behavior of the spec.

    • Added clarification to case sensitivity of keys in maps.
    • Reworked the Data Type table, removing the Common Name to reduce potential confusion.
    • Clarified the description of the Server Variable Object's default field.
    • Fixed various examples.
    • Clarified operationId is case sensitive.
    • Clarified the default value of the Parameter Object's deprecated field is false.
    • Added recommendation to not use the Parameter Object's allowEmptyValue field as it will be removed in a future version.
    • Fixed the description of the Media Type Object's schema field.
    • Clarified the description of the Responses Object's response codes field description.
    • Clarified that the Schema Object's additionalProperties field has a default value of true.
    • Fixed a small wording issue in the Discriminator Object description.
    • Fixed the Security Scheme Object description to include reference to the use of API Keys in cookies.
    • Fixed the description of the Security Requirement Object.
    Source code(tar.gz)
    Source code(zip)
  • 3.0.1(Dec 7, 2017)

    OAS 3.0.1 Change Log

    The OAI is pleased to announce the official release of the OpenAPI Specification 3.0.1!

    This our first patch release since 3.0.0, containing the following updates:

    Specification Changes

    • Updated document links to HTTPS where applicable.
    • example and examples fields descriptions were updated to reference them as 'fields' and not 'objects'.
    • Fixed various examples (indentation, field names, comments).
    • Removed the Examples Object as it was left over during editing of v3.0.0. It was not used or referenced to by any other object in the specification.
    • Various typo fixes.

    Additional Changes

    • Clarified the roles and processes in the Technical Steering Committee (TSC, formerly the TDC).
    • Improvements to the development guidelines.
    Source code(tar.gz)
    Source code(zip)
  • 3.0.0(Jul 26, 2017)

    OAS 3.0.0 Change Log

    The OAI is pleased to announce the official release of the OpenAPI Specification 3.0.0!

    The list below reflect the changes since the last release candidate.

    Schema Changes

    • The headers map under the Encoding Object can now also reference headers.

    Descriptive Changes

    • Reworded descriptions for clearer intent (no change of meaning).
    • The OpenAPI Definition File has been renamed as the OpenAPI Document.
    • Changes to better conform to RFC 2119.
    • Elaborated Request Body's and Response's content field support media type ranges.
    • Fixed descriptions of operationRef and operationId under the Link Object. Also clarified that a Link MUST contain one of them.
    • Added links to OAuth2's and OpenID Connect's specifications.

    Document Changes

    • Some example fixes.

    Check it out! https://github.com/OAI/OpenAPI-Specification/blob/3.0.0/versions/3.0.0.md

    Source code(tar.gz)
    Source code(zip)
  • 3.0.0-rc2(Jun 17, 2017)

    OAS 3.0.0-rc2 Change Log

    Schema Changes

    • The following objects have been removed from the specification: Server Variables, Content, Encoding, Callbacks, Headers, Links, Link Parameters, Scopes. They have all been replaced by the Map construct being effectively what they are. Clarifies that specification extensions are not allowed, as they did not make sense.
    • The Encoding Property Object has been renamed to the Encoding Object. This is a result of the above change.
    • The Encoding Object now specifies to which media type each property is applicable.
    • The Encoding Object now defines headers as a map of Header Objects.
    • The different components under the Components Object can now either be defined inline or referenced.
    • For parameters using content, now only one media type can be used at most.
    • The headers property under the Link Object has been removed.
    • Link Object has a new requestBody property to allow passing a request body.
    • The Schema Object's discriminator property has been completely reworked to utilize the newly supported oneOf and anyOf. A new Discriminator Object has been added to support these changes.
    • The XML Object's namespace now MUST be an absolute URI.
    • The apiKey security scheme can now also be in cookie.

    Descriptive Changes

    • The Rich Text Formatting section has been reworded to ease the requirements.
    • Added OpenAPI Definition File definition.
    • Clarified that an empty or nonexisting servers would default to a single Server with the url value of /.
    • Reworded the section explaining the specification's versioning scheme.
    • Server Variable enum's description has been fixed to state it can only be a string (the type was correct).
    • Added clarification + examples how path matching works for paths defined under the Paths Object.
    • Removed recommendation for a 120 character limit for the summary field under the Operation Object.
    • Further details added to the form and simple types of style.
    • Clarified that the Encoding Object applies to both multipart and application/x-www-form-urlencoded and only those.
    • Clarified the possible response code wildcards are only 1XX, 2XX, 3XX, 4XX or 5XX.
    • Variable Expressions have been renamed to Runtime Expressions. They have been unified between Links and Callbacks, and have a dedicated section. Various examples have been moved and removed as a result.
    • Runtime expressions now use curly braces when found inside strings.
    • Link Object's parameters now defines how to deal with cases of parameter name ambiguity.

    Document Changes

    • ToC has been updated to reflect changes.
    • Fixed various anchors in the document.
    • Various examples have been fixed.
    • Various editorial changes were made to make the document more readable.

    Check it out! https://github.com/OAI/OpenAPI-Specification/blob/3.0.0-rc2/versions/3.0.md

    Source code(tar.gz)
    Source code(zip)
  • 3.0.0-rc1(Apr 28, 2017)

    OAS 3.0.0-rc1 Change Log

    Schema Changes

    • url is now required under the Server Object.
    • Server Variable Object's enum and default values are now string only (were any primitive).
    • servers under the Path Item Object and Operation Object has been fixed to be an array of Server Objects and not a single one.
    • The example and examples fields have been reworked, alongside the Example Object. There is no longer examples field under the Schema Object. Where examples exist, they are now a map of named examples with additional metadata for each example. The Example Object now has defined fields and is not free-form.
    • content is now required under the Request Body Object.
    • href under the Link Object has been renamed to operationRef, its description is clarified as well.
    • The deprecated field under the Schema Object now defaults to false.
    • The flow field under the Security Scheme Object has been renamed to flows.
    • Request Body's required now defaults to false.
    • Added allowReserved to the Encoding Property Object.

    Descriptive Changes

    • termsOfService now MUST be in the form of a URL.
    • all description fields now support CommonMark.
    • Clarified that specific response codes (200 for example) take precedence over response ranges (2XX for example).
    • Clarified that for Parameter Object, either schema or content are required.
    • pattern under the Schema Object now specifies the regex flavor.
    • Added header restrictions. "Accept", "Content-Type", "Authorization" header paramters and "Content-Type" response headers will now be ignored.
    • Referenced a specific version of supported CommonMark.
    • Added clarifications to null not being a type (as opposed to a value).

    Document Changes

    • ToC has been updated to reflect changes.
    • Fixed various anchors in the document.
    • Various examples have been fixed.

    Check it out! https://github.com/OAI/OpenAPI-Specification/blob/3.0.0-rc1/versions/3.0.md

    Source code(tar.gz)
    Source code(zip)
  • 3.0.0-rc0(Mar 1, 2017)

    We're happy to announce the release of the first Implementer's Draft of OAS 3.0.0, known as 3.0.0-rc0.

    A lot of changes in this release, as a first one goes, so expect the change log to be updated. An initial list of changes, in no particular order:

    • Changed the versioning scheme of the spec.
    • Reusable definitions in the spec has been expanded and reorganized under the Components Object.
    • Added support for operation callbacks.
    • Added support for a new static linking between responses and operations.
    • Reworked parameters - removed formData parameters, added cookie parameters, changed body parameters to Request Body Objects as a separate entity.
    • Parameters now support complex types.
    • Responses support multiple media type specifications.
    • Reworked file support. Dropped file as a type, but provided better handling for file uploads and downloads.
    • Reworked security definitions to allow for support for more schemes.
    • Improved support for examples throughout the spec.
    • Added support for defining multiple servers hosting the API, including URL variables.

    Check it out! https://github.com/OAI/OpenAPI-Specification/blob/3.0.0-rc0/versions/3.0.md

    Our blog post contains more details of the process and next steps.

    Source code(tar.gz)
    Source code(zip)
Owner
OpenAPI Initiative
OpenAPI Initiative
Automated generation of real Swagger/OpenAPI 2.0 schemas from Django REST Framework code.

drf-yasg - Yet another Swagger generator Generate real Swagger/OpenAPI 2.0 specifications from a Django Rest Framework API. Compatible with Django Res

Cristi Vîjdea 3k Dec 31, 2022
Sane and flexible OpenAPI 3 schema generation for Django REST framework.

drf-spectacular Sane and flexible OpenAPI 3.0 schema generation for Django REST framework. This project has 3 goals: Extract as much schema informatio

T. Franzel 1.4k Jan 8, 2023
Test utility for validating OpenAPI documentation

DRF OpenAPI Tester This is a test utility to validate DRF Test Responses against OpenAPI 2 and 3 schema. It has built-in support for: OpenAPI 2/3 yaml

snok 106 Jan 5, 2023
In this Github repository I will share my freqtrade files with you. I want to help people with this repository who don't know Freqtrade so much yet.

My Freqtrade stuff In this Github repository I will share my freqtrade files with you. I want to help people with this repository who don't know Freqt

Simon Kebekus 104 Dec 31, 2022
Main repository for the Sphinx documentation builder

Sphinx Sphinx is a tool that makes it easy to create intelligent and beautiful documentation for Python projects (or other documents consisting of mul

null 5.1k Jan 2, 2023
Main repository for the Sphinx documentation builder

Sphinx Sphinx is a tool that makes it easy to create intelligent and beautiful documentation for Python projects (or other documents consisting of mul

null 5.1k Jan 4, 2023
Generate a single PDF file from MkDocs repository.

PDF Generate Plugin for MkDocs This plugin will generate a single PDF file from your MkDocs repository. This plugin is inspired by MkDocs PDF Export P

null 198 Jan 3, 2023
Canonical source repository for PyYAML

PyYAML - The next generation YAML parser and emitter for Python. To install, type 'python setup.py install'. By default, the setup.py script checks

The YAML Project 2k Jan 1, 2023
This is a repository for "100 days of code challenge" projects. You can reach all projects from beginner to professional which are written in Python.

100 Days of Code It's a challenge that aims to gain code practice and enhance programming knowledge. Day #1 Create a Band Name Generator It's actually

SelenNB 2 May 12, 2022
This repository outlines deploying a local Kubeflow v1.3 instance on microk8s and deploying a simple MNIST classifier using KFServing.

Zero to Inference with Kubeflow Getting Started This repository houses all of the tools, utilities, and example pipeline implementations for exploring

Ed Henry 3 May 18, 2022
Repository for learning Python (Python Tutorial)

Repository for learning Python (Python Tutorial) Languages and Tools ?? Overview ?? Repository for learning Python (Python Tutorial) Languages and Too

Swiftman 2 Aug 22, 2022
SCTYMN is a GitHub repository that includes some simple scripts(currently only python scripts) that can be useful.

Simple Codes That You Might Need SCTYMN is a GitHub repository that includes some simple scripts(currently only python scripts) that can be useful. In

CodeWriter21 2 Jan 21, 2022
Repository for tutorials, examples and starter scripts for using the MTU HPC cluster

MTU-HPC-Starter Repository for tutorials, examples and starter scripts for using the MTU HPC cluster Connecting to the MTU HPC cluster Within the coll

null 1 Jan 31, 2022
Python interface to Oracle Database conforming to the Python DB API 2.0 specification.

cx_Oracle version 8.2 (Development) cx_Oracle is a Python extension module that enables access to Oracle Database. It conforms to the Python database

Oracle 841 Dec 21, 2022
A Plover python dictionary allowing for consistent symbol input with specification of attachment and capitalisation in one stroke.

Emily's Symbol Dictionary Design This dictionary was created with the following goals in mind: Have a consistent method to type (pretty much) every sy

Emily 68 Jan 7, 2023
Lumen provides a framework for visual analytics, which allows users to build data-driven dashboards from a simple yaml specification

Lumen project provides a framework for visual analytics, which allows users to build data-driven dashboards from a simple yaml specification

HoloViz 120 Jan 4, 2023
Data derived from the OpenType specification

This package currently provides the opentypespec.tags module, which exports FEATURE_TAGS, SCRIPT_TAGS, LANGUAGE_TAGS and BASELINE_TAGS dictionaries, representing data from the Layout Tag Registry

Simon Cozens 4 Dec 1, 2022
A Python module and command line utility for working with web archive data using the WACZ format specification

py-wacz The py-wacz repository contains a Python module and command line utility for working with web archive data using the WACZ format specification

Webrecorder 14 Oct 24, 2022
Histogram specification using openCV in python .

histogram specification using openCV in python . Have to input miu and sigma to draw gausssian distribution which will be used to map the input image . Example input can be miu = 128 sigma = 30

Tamzid hasan 6 Nov 17, 2021
Specification for storing geospatial vector data (point, line, polygon) in Parquet

GeoParquet About This repository defines how to store geospatial vector data (point, lines, polygons) in Apache Parquet, a popular columnar storage fo

Open Geospatial Consortium 449 Dec 27, 2022