OpenAPI Specification

From Wikipedia, the free encyclopedia
Jump to navigation Jump to search

The OpenAPI Specification, originally known as the Swagger Specification, is a specification for machine-readable interface files for describing, producing, consuming, and visualizing RESTful web services.[1] Originally part of the Swagger framework, it became a separate project in 2016, overseen by the OpenAPI Initiative, an open source collaborative project of the Linux Foundation.[2] Swagger and some other tools can generate code, documentation and test cases given an interface file.

History[edit]

Swagger development began in early 2010. In March 2015, SmartBear Software acquired the open source Swagger API specification from Reverb Technologies.[3]

In November 2015, SmartBear, the company that maintained the Swagger specification and associated tools, announced that it was helping create a new organization, under the sponsorship of the Linux Foundation, called the Open API Initiative. A variety of companies, including Google, IBM and Microsoft are founding members.[4][5] SmartBear donated the Swagger specification to the new group. RAML and API Blueprint were also under consideration by the group.[6][7]

On 1 January 2016, the Swagger specification was renamed the OpenAPI Specification, and was moved to a new repository in GitHub.

In September 2016, the API World conference presented an API Infrastructure award to SmartBear for its ongoing work on Swagger.[8]

In July 2017, the OpenAPI Initiative released version 3.0.0 of its specification.[9] MuleSoft, the main contributor to the alternative RESTful API Modeling Language (RAML), joined the OAS and open sourced their API Modeling Framework tool, which can generate OAS documents from RAML input.[10]

Usage[edit]

Applications implemented based on OpenAPI interface files can automatically generate documentation of methods, parameters and models. This helps keep the documentation, client libraries, and source code in sync.[11]

Features[edit]

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.[11]

OpenAPI interface files can be audited for security vulnerabilities.[12]

Tools that work with OpenAPI[edit]

The OpenAPI Initiative maintains a list of implementations for version 3.0 of the specification. Unofficial lists also exist.

SmartBear still brand their OpenAPI tools with the Swagger moniker.

The Swagger UI framework allows both developers and non-developers to interact with the API in a sandbox UI that gives insight into how the API responds to parameters and options. Swagger can handle both JSON and XML.[11]

Swagger-Codegen contains a template-driven engine to generate documentation, API clients and server stubs in different languages by parsing the OpenAPI definition.

See also[edit]

References[edit]

  1. ^ "Linux Foundation wants to extend Swagger in connected buildings | Business Cloud News". Retrieved 2016-04-22.
  2. ^ https://openapis.org/governance
  3. ^ "SmartBear Assumes Sponsorship of Swagger API Open Source Project". SmartBear. Retrieved 2015-03-25.
  4. ^ "SmartBear, Linux Foundation launch Open API Initiative to Evolve Swagger". ProgrammableWeb. 2015-11-10. Retrieved 2016-04-21.
  5. ^ "New Collaborative Project to Extend Swagger Specification for Building Connected Applications and Services". www.linuxfoundation.org. Archived from the original on 2016-04-27. Retrieved 2016-04-22.
  6. ^ Montcheuil, Yves de. "In 2016, the need for an API meta-language will crystallize". InfoWorld. Retrieved 2016-04-25.
  7. ^ "Amazon API Gateway Now Supports Swagger Definition Import". InfoQ. Retrieved 2016-04-25.
  8. ^ "Swagger wins the 2016 API Award for API Infrastructure". Swagger Blog. Retrieved 2018-07-27.
  9. ^ "The OAI Announces the OpenAPI Specification 3.0.0". OpenAPIs. Retrieved 2018-04-19.
  10. ^ "The HTTP API space is Consolidating around OAS". InfoQ. Retrieved 2017-05-14.
  11. ^ a b c "swagger-api/swagger-spec". GitHub. Retrieved 2015-12-01.
  12. ^ "API Contract Security Audit free online tool". apisecurity.io. Retrieved 2019-02-15.

Bibliography[edit]

  • Haupt, F.; Karastoyanova, D.; Leymann, F.; Schroth, B. (2014). A Model-Driven Approach for REST Compliant Services. ICWS 2014. 2014 IEEE International Conference on Web Services. pp. 129–136. doi:10.1109/ICWS.2014.30. ISBN 978-1-4799-5054-6.

External links[edit]