# A brief introduction to OpenAPI

DevFeed: [A brief introduction to OpenAPI](<https://devfeed.tech/articles/a-brief-introduction-to-openapi-19081.md>)

Original publisher: [Read original article](<https://httptoolkit.com/blog/introduction-to-openapi/>)

Author: HTTP Toolkit; Phil Sturgeon

Published: 2023-11-28T09:30:00Z

Content type: tutorial

Language: en

Sources: [HTTP Toolkit](<https://devfeed.tech/sources/http-toolkit.md>)

Topics: [OpenAPI Specification](<https://devfeed.tech/topics/openapi.md>), [API](<https://devfeed.tech/topics/api.md>), [HTTP](<https://devfeed.tech/topics/http.md>), [JSON Schema](<https://devfeed.tech/topics/json-schema.md>), [Documentation](<https://devfeed.tech/topics/documentation.md>), [JSON](<https://devfeed.tech/topics/json.md>), [SDKs](<https://devfeed.tech/topics/sdks.md>), [Testing](<https://devfeed.tech/topics/testing.md>)

Tags: [api](<https://devfeed.tech/tags/api.md>), [api-documentation](<https://devfeed.tech/tags/api-documentation.md>), [apis](<https://devfeed.tech/tags/apis.md>), [graphql](<https://devfeed.tech/tags/graphql.md>), [http](<https://devfeed.tech/tags/http.md>), [json-schema](<https://devfeed.tech/tags/json-schema.md>), [openapi](<https://devfeed.tech/tags/openapi.md>), [sdks](<https://devfeed.tech/tags/sdks.md>), [standards](<https://devfeed.tech/tags/standards.md>), [swagger](<https://devfeed.tech/tags/swagger.md>), [validation](<https://devfeed.tech/tags/validation.md>)

## AI overview

An introduction to OpenAPI as a machine-readable description format for HTTP APIs. The article explains how OpenAPI describes endpoints, requests, responses, authentication, and validation, and how it supports documentation, testing, validation, SDK generation, server stubs, and mock servers.

## Source excerpt

It's hard to work on APIs without hearing about OpenAPI. OpenAPI is an API description format, which is essentially metadata that describes an HTTP API: where it lives, how it works, what data is available, and how it's authenticated. Additional keywords can be used to provide all sorts of validation information, adding a type system to what would otherwise just be arbitrary JSON flying around the internet. OpenAPI has been around for donkeys years, previously known as Swagger but renamed to OpenAPI in 2016. It's powered by JSON Schema, which is also pretty popular in certain circles, but it's only in the last few years that OpenAPI has solidified its place as the description format for HTTP APIs, pushing aside others like RAML and API Blueprint. Elder developers will remember working with WSDLs and XML Schema, and gRPC and GraphQL folks might be thinking "hang on this sounds a bit familiar", and absolutely. Type systems for APIs are pretty common, but here's an excellent one you can use for your REST/RESTish API. Here's an example to give you an idea: openapi: 3.1.3 info: title: Your Awesome API version: '1.0.3' description: More information and introduction. paths: /things: post: summary: Create a thing requestBody: content: application/json: schema: type: object properties: name: type: string examples: - Tim responses: '201': description: "Created" content: application/json: schema: type: object properties: id: type: string format: uuid name: type: string examples: - Tim created_at: type: string format: date-time example: 2020-01-01T00:00:00Z This describes an API in a machine-readable format, including overall metadata, endpoint paths, request formats, and the details of possible responses you might receive. What can OpenAPI do? OpenAPI specifications provide a machine-readable base on top of which lots of neat API tools can be used and even generated. One of the most common uses by many API teams to to generate API reference documentation, which helps end-users