OpenAPI Specification

Last updated
OpenAPI
OpenAPI Specification
OpenAPI Specification Logo Pantone.svg
Year started2010 (2010)
First published10 August 2011 (2011-08-10)
Latest version3.1.1
24 October 2024 (2024-10-24)
Website openapis.org

The OpenAPI Specification, previously known as the Swagger Specification, is a specification for a machine-readable interface definition language for describing, producing, consuming and visualizing web services. [1] Originally developed to support the Swagger framework, it became a separate project in 2015, overseen by the OpenAPI Initiative, an open-source collaboration project of the Linux Foundation. [2] [3]

Contents

An OpenAPI Description (OAD) [4] represents a formal description of an API that tools can use to generate code, documentation, test cases, and more.

History

Logo of the OpenAPI Initiative, the organization that develops the OpenAPI specification under the Linux Foundation OpenAPI Logo Pantone.svg
Logo of the OpenAPI Initiative, the organization that develops the OpenAPI specification under the Linux Foundation

Swagger development began in early 2010 by Tony Tam, who was working at online dictionary company Wordnik. [5]

In March 2015, SmartBear Software acquired the open-source Swagger API specification from Reverb Technologies, Wordnik's parent company. [6]

In November 2015, SmartBear announced that it was donating the Swagger specification to a new organization called the OpenAPI Initiative, under the sponsorship of the Linux Foundation. Other founding member companies included 3scale, Apigee, Capital One, Google, IBM, Intuit, Microsoft, PayPal, and Restlet. [7] [8]

On 1 January 2016, the Swagger specification was renamed the OpenAPI Specification (OAS) and was moved to a new GitHub repository. [9]

In July 2017, the OpenAPI Initiative released version 3.0.0 of its specification. [10]

In February 2021, the OpenAPI Initiative released version 3.1.0. [11] Major changes in OpenAPI Specification 3.1.0 include JSON schema vocabularies alignment, new top-level elements for describing webhooks that are registered and managed out of band, support for identifying API licenses using the standard SPDX identifier, allowance of descriptions alongside the use of schema references and a change to make the PathItems object optional to simplify creation of reusable libraries of components. [12] [13] [14]

Consolidation of Formats

Two somewhat similar technologies, MuleSoft's RESTful API Modeling Language (RAML) and Apiary's API Blueprint, had been developed around the same time as what was then still called the Swagger Specification.

The producers of both formats later joined the OpenAPI Initiative: Apiary in 2016 [15] and MuleSoft in 2017. [16] Both have added support for the OAS. [17] [16]

Release dates

VersionDateNotes [18]
3.1.02021-02-15Release of the OpenAPI Specification 3.1.0
3.0.32020-02-20Patch release of the OpenAPI Specification 3.0.3
3.0.22018-10-08Patch release of the OpenAPI Specification 3.0.2
3.0.12017-12-06Patch release of the OpenAPI Specification 3.0.1
3.0.02017-07-26Release of the OpenAPI Specification 3.0.0
2.02014-09-08Release of Swagger 2.0
1.22014-03-14Initial release of the formal document
1.12012-08-22Release of Swagger 1.1
1.02011-08-10First release of the Swagger Specification

Usage

The OAS describes the format for OpenAPI Descriptions (OADs), [4] which can be used by a variety of applications, libraries, and tools.

Applications can use OADs to automatically generate documentation of methods, parameters and data models. This helps keep the documentation, client libraries and source code in sync. [19]

When an OAD is used to generate source code stubs for servers, the process is called scaffolding.

Relationships to software engineering practices

The paradigm of agreeing on an API contract first and then programming business logic afterwards, in contrast to coding the program first and then writing a retrospective description of its behavior as the contract, is called contract-first development. Since the interface is determined before any code is written, downstream developers can mock the server behavior and start testing right away. [20] In this sense, contract-first development is also a practice of shift-left testing.

Features

The OpenAPI Specification is language-agnostic. With OpenAPI's declarative resource specification, clients can understand and consume services without knowledge of server implementation or access to the server code. [1]

Tools that work with OpenAPI

The OpenAPI Initiative maintains a list of implementations for version 3.0 of the specification. [21]

Annual conference

The OpenAPI Initiative sponsors an annual API Specifications Conference (ASC). The event has its origins in the API Strategy and Practice Conference (APIStrat) that ran for many years and became part of the OpenAPI Initiative in 2016.

See also

Related Research Articles

<span class="mw-page-title-main">Free and open-source graphics device driver</span> Software that controls computer-graphics hardware

A free and open-source graphics device driver is a software stack which controls computer-graphics hardware and supports graphics-rendering application programming interfaces (APIs) and is released under a free and open-source software license. Graphics device drivers are written for specific hardware to work within a specific operating system kernel and to support a range of APIs used by applications to access the graphics hardware. They may also control output to the display if the display driver is part of the graphics hardware. Most free and open-source graphics device drivers are developed by the Mesa project. The driver is made up of a compiler, a rendering API, and software which manages access to the graphics hardware.


This is a comparison of notable free and open-source configuration management software, suitable for tasks like server configuration, orchestration and infrastructure as code typically performed by a system administrator.

An open API is a publicly available application programming interface that provides developers with programmatic access to a software application or web service. Open APIs are APIs that are published on the internet and are free to access by consumers.

Bitbucket is a Git-based source code repository hosting service owned by Atlassian. Bitbucket offers both commercial plans and free accounts with an unlimited number of private repositories.

The Common Manageability Programming Interface is an open standard that defines a programming interface between a WBEM server and WBEM providers.

<span class="mw-page-title-main">Node.js</span> JavaScript runtime environment

Node.js is a cross-platform, open-source JavaScript runtime environment that can run on Windows, Linux, Unix, macOS, and more. Node.js runs on the V8 JavaScript engine, and executes JavaScript code outside a web browser.

Dart is a programming language designed by Lars Bak and Kasper Lund and developed by Google. It can be used to develop web and mobile apps as well as server and desktop applications.

Docker is a set of platform as a service (PaaS) products that use OS-level virtualization to deliver software in packages called containers. The service has both free and premium tiers. The software that hosts the containers is called Docker Engine. It was first released in 2013 and is developed by Docker, Inc.

RESTful API Modeling Language (RAML) is a YAML-based language for describing static APIs. It provides all the information necessary to describe APIs on the level 2 of the Richardson Maturity Model. Although designed with RESTful APIs in mind, RAML is not capable of describing APIs that obey all constraints of REST. It encourages reuse, enables discovery and pattern-sharing and aims for merit-based emergence of best practices.

Vulkan is a low-level, low-overhead cross-platform API and open standard for 3D graphics and computing. It was intended to address the shortcomings of OpenGL, and allow developers more control over the GPU. It is designed to support a wide variety of GPUs, CPUs and operating systems, and it is also designed to work with modern multi-core CPUs.

<span class="mw-page-title-main">GPUOpen</span> Middleware software suite

GPUOpen is a middleware software suite originally developed by AMD's Radeon Technologies Group that offers advanced visual effects for computer games. It was released in 2016. GPUOpen serves as an alternative to, and a direct competitor of Nvidia GameWorks. GPUOpen is similar to GameWorks in that it encompasses several different graphics technologies as its main components that were previously independent and separate from one another. However, GPUOpen is partially open source software, unlike GameWorks which is proprietary and closed.

<span class="mw-page-title-main">Swagger (software)</span> Computing language

Swagger is a suite of tools for API developers from SmartBear Software and a former specification upon which the OpenAPI Specification is based.

The Open Container Initiative (OCI) is a Linux Foundation project, started in June 2015 by Docker, CoreOS, and the maintainers of appc to design open standards for operating system-level virtualization (containers). At launch, OCI was focused on Linux containers and subsequent work has extended it to other operating systems.

<span class="mw-page-title-main">ROCm</span> Parallel computing platform: GPGPU libraries and application programming interface

ROCm is an Advanced Micro Devices (AMD) software stack for graphics processing unit (GPU) programming. ROCm spans several domains: general-purpose computing on graphics processing units (GPGPU), high performance computing (HPC), heterogeneous computing. It offers several programming models: HIP, OpenMP, and OpenCL.

The Redfish standard is a suite of specifications that deliver an industry standard protocol providing a RESTful interface for the management of servers, storage, networking, and converged infrastructure.

Microsoft, a tech company historically known for its opposition to the open source software paradigm, turned to embrace the approach in the 2010s. From the 1970s through 2000s under CEOs Bill Gates and Steve Ballmer, Microsoft viewed the community creation and sharing of communal code, later to be known as free and open source software, as a threat to its business, and both executives spoke negatively against it. In the 2010s, as the industry turned towards cloud, embedded, and mobile computing—technologies powered by open source advances—CEO Satya Nadella led Microsoft towards open source adoption although Microsoft's traditional Windows business continued to grow throughout this period generating revenues of 26.8 billion in the third quarter of 2018, while Microsoft's Azure cloud revenues nearly doubled.

FastAPI is a high-performance web framework for building HTTP-based service APIs in Python 3.8+. It uses Pydantic and type hints to validate, serialize and deserialize data. FastAPI also automatically generates OpenAPI documentation for APIs built with it. It was first released in 2018.

<span class="mw-page-title-main">OpenHarmony</span> Family of open-source operating systems based on OpenHarmony

OpenHarmony is a family of open-source distributed operating systems based on HarmonyOS derived from LiteOS, donated the L0-L2 branch source code by Huawei to the OpenAtom Foundation. Similar to HarmonyOS, the open-source distributed operating system is designed with a layered architecture, consisting of four layers from the bottom to the top: the kernel layer, system service layer, framework layer, and application layer. It is also an extensive collection of free software, which can be used as an operating system or in parts with other operating systems via Kernel Abstraction Layer subsystems.

References

  1. 1 2 "OpenAPI Documentation: Getting Started". Learn OpenAPI. The OpenAPI Initiative. Retrieved 17 September 2024.
  2. ↑ "New Collaborative Project to Extend Swagger Specification for Building Connected Applications and Services". Archived from the original on 31 October 2023.
  3. ↑ "OpenAPI Initiative Charter". OpenAPI Initiative. Retrieved 12 November 2019.
  4. 1 2 "OpenAPI Documentation: Glossary". Learn OpenAPI. The OpenAPI Initiative. 2023. Retrieved 17 September 2024.
  5. ↑ "Swagger creator joins SmartBear". 28 September 2015. Retrieved 6 August 2019.
  6. ↑ "SmartBear Assumes Sponsorship of Swagger API Open Source Project". SmartBear. Retrieved 25 March 2015.
  7. ↑ "FAQ". OpenAPI Initiative. Retrieved 12 November 2019.
  8. ↑ "New Collaborative Project to Extend Swagger Specification for Building Connected Applications and Services". linuxfoundation.org. Archived from the original on 27 April 2016. Retrieved 22 April 2016.
  9. ↑ OpenAPI Initiative. "OpenAPI Specification". GitHub. Retrieved 12 November 2019.
  10. ↑ "The OAI Announces the OpenAPI Specification 3.0.0". OpenAPIs. 26 July 2017. Retrieved 19 April 2018.
  11. ↑ "OpenAPI Specification 3.1.0 Available Now". Linux.com. 26 April 2021. Retrieved 26 April 2021.
  12. ↑ Charboneau, Tyler (7 April 2021). "What's New in OpenAPI 3.1.0?". Nordic APIs. Retrieved 7 April 2021.
  13. ↑ "OpenAPI Specification 3.1.0 Released". OpenAPI Initiative. 18 February 2021. Retrieved 18 February 2021.
  14. ↑ Sturgeon, Phil (16 February 2021). "Migrating from OpenAPI 3.0 to 3.1.0". OpenAPI Initiative. Retrieved 16 February 2021.
  15. ↑ Lensmar, Ole (23 February 2016). "OAI Update – new members, OpenAPI Spec 3.0 progress, and more!". The OpenAPI Initiative. Retrieved 13 October 2024.
  16. 1 2 Avram, Abel (6 May 2017). "The HTTP API space is Consolidating around OAS". InfoQ. Retrieved 14 May 2017.
  17. ↑ Nesetril, Jakub (18 January 2016). "We've got Swagger". Oracle Apiary. Retrieved 13 October 2024.
  18. ↑ "OpenAPI Specification Version 3.1.0". GitHub. Retrieved 7 November 2023.
  19. ↑ "OpenAPI Documentation: Introduction". Learn OpenAPI. The OpenAPI Initiative. 2023. Retrieved 17 September 2024.
  20. ↑ Preibisch, Sascha (2018). API Development: A Practical Guide for Business Implementation Success. [Berkeley, CA]: Apress. ISBN   978-1-4842-4140-0. OCLC   1076234393. Having the Swagger (or for that matter, any other machine-readable) document available, team members can start working on their part of the project at the same time.
  21. ↑ "OpenAPI Tooling". OpenAPI Tooling. The OpenAPI Initiative. Retrieved 17 September 2024.

Bibliography

This page is based on this Wikipedia article
Text is available under the CC BY-SA 4.0 license; additional terms may apply.
Images, videos and audio are available under their respective licenses.