Example.com (1.0.0)

Download OpenAPI specification:Download

This is an example API to demonstrate features of OpenAPI specification

Introduction

This API definition is intended to to be a good starting point for describing your API in OpenAPI/Swagger format. It also demonstrates features of create-openapi-repo tool and Redoc documentation engine. So beyond the standard OpenAPI syntax we use a few vendor extensions.

My video embed

OpenAPI Specification

The goal of The OpenAPI Specification is to define a standard, language-agnostic interface to REST APIs which allows both humans and computers to discover and understand the capabilities of the service without access to source code, documentation, or through network traffic inspection. 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 interfaces have done for lower-level programming, OpenAPI removes the guesswork in calling the service.

Authentication

main_auth

Security Scheme Type OAuth2
implicit OAuth Flow
Authorization URL: http://example.com/api/oauth/dialog
Scopes:
  • read:users -

    read users info

  • write:users -

    modify or remove users

api_key

Security Scheme Type API Key
Header parameter name: api_key

basic_auth

Security Scheme Type HTTP
HTTP Authorization Scheme basic

Echo

Example echo operations

Try it

Echo test

Receive the exact message you've sent

Authorizations:
Request Body schema:

Echo payload

string

Responses

Request samples

Content type
"Hello world!"

Response samples

Content type
"Hello world!"

User

Operations about user

Try it

Get user by user name

Some description of the operation. You can use markdown here.

Authorizations:
main_auth (read:users) api_key
path Parameters
username
required
string

The name that needs to be fetched

query Parameters
pretty_print
boolean

Pretty print response

with_email
boolean

Filter users without email

Responses

Response samples

Content type
application/json
{
  • "username": "user1",
  • "email": "user@example.com"
}
Try it

Updated user

This can only be done by the logged in user.

Authorizations:
main_auth (write:users)
path Parameters
username
required
string

The name that needs to be updated

query Parameters
pretty_print
boolean

Pretty print response

Request Body schema:

Updated user object

username
string >= 4 characters

User supplied username

firstName
string non-empty

User first name

lastName
string non-empty

User last name

email
string <test> (Email)

User email address

Responses

Request samples

Content type
{
  • "username": "John78",
  • "firstName": "John",
  • "lastName": "Smith",
  • "email": "john.smith@example.com"
}