Init OpenAPI template

This commit is contained in:
GHOSCHT 2024-05-22 21:53:09 +02:00
commit 968a1d1e97
Signed by: ghoscht
GPG key ID: 2C2C1C62A5388E82

223
openapi.yml Normal file
View file

@ -0,0 +1,223 @@
# This is an **example** API to demonstrate features of OpenAPI specification.
# It doesn't cover all OpenAPI features. For more full example check out: https://github.com/APIs-guru/petstore_extended
openapi: 3.0.2
info:
version: '1.0.0' # Your API version
# It can be any string but it is better to use semantic versioning: http://semver.org/
# Warning: OpenAPI requires the version to be a string, but without quotation marks YAML can recognize it as a number.
title: Example.com # Replace with your API title
# Keep it simple. Don't add "API" or version at the end of the string.
termsOfService: 'https://example.com/terms/' # [Optional] Replace with an URL to your ToS
contact:
email: contact@example.com # [Optional] Replace with your contact email
url: 'http://example.com/contact' # [Optional] Replace with link to your contact form
license:
name: Apache 2.0
url: 'http://www.apache.org/licenses/LICENSE-2.0.html'
x-logo:
url: 'https://redocly.github.io/openapi-template/logo.png'
# Describe your API here, you can use GFM (https://guides.github.com/features/mastering-markdown) here
description: "This is an **example** API to demonstrate features of OpenAPI specification\n# Introduction\nThis API definition is intended to to be a good starting point for describing your API in \n[OpenAPI/Swagger format](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md).\nIt also demonstrates features of [create-openapi-repo](https://github.com/Redocly/create-openapi-repo) tool and \n[Redoc](https://github.com/Redocly/Redoc) documentation engine. So beyond the standard OpenAPI syntax we use a few \n[vendor extensions](https://github.com/Redocly/Redoc/blob/master/docs/redoc-vendor-extensions.md).\n\n# OpenAPI Specification\nThe goal of The OpenAPI Specification is to define a standard, language-agnostic interface to REST APIs which\nallows both humans and computers to discover and understand the capabilities of the service without access to source\ncode, documentation, or through network traffic inspection. When properly defined via OpenAPI, a consumer can \nunderstand and interact with the remote service with a minimal amount of implementation logic. Similar to what\ninterfaces have done for lower-level programming, OpenAPI removes the guesswork in calling the service.\n"
externalDocs:
description: Find out how to create a GitHub repo for your OpenAPI definition.
url: 'https://github.com/Rebilly/generator-openapi-repo'
# A list of tags used by the definition with additional metadata.
# The order of the tags can be used to reflect on their order by the parsing tools.
tags:
- name: Echo
description: Example echo operations
- name: User
description: Operations about user
servers:
- url: 'http://example.com/api/v1'
- url: 'https://example.com/api/v1'
# Holds the relative paths to the individual endpoints. The path is appended to the
# basePath in order to construct the full URL.
paths:
'/users/{username}': # path parameter in curly braces
# parameters list that are used with each operation for this path
parameters:
- name: pretty_print
in: query
description: Pretty print response
schema:
type: boolean
get: # documentation for GET operation for this path
tags:
- User
# summary is up to 120 symbold but we recommend to be shortest as possible
summary: Get user by user name
# you can use GFM in operation description too: https://guides.github.com/features/mastering-markdown
description: "Some description of the operation. \nYou can use `markdown` here.\n"
# operationId should be unique across the whole specification
operationId: getUserByName
# list of parameters for the operation
parameters:
- name: username
in: path
description: The name that needs to be fetched
required: true
schema:
type: string
- name: with_email
in: query
description: Filter users without email
schema:
type: boolean
# security schemas applied to this operation
security:
- main_auth:
- 'read:users' # for oauth2 provide list of scopes here
- api_key: []
responses: # list of responses
'200':
description: Success
content:
application/json: # operation response mime type
schema: # response schema can be specified for each response
$ref: '#/components/schemas/User'
example: # response example
username: user1
email: user@example.com
'403':
description: Forbidden
'404':
description: User not found
# documentation for PUT operation for this path
put:
tags:
- User
summary: Updated user
description: This can only be done by the logged in user.
operationId: updateUser
parameters:
- name: username
in: path
description: The name that needs to be updated
required: true
schema:
type: string
security:
- main_auth:
- 'write:users'
responses:
'200':
description: OK
'400':
description: Invalid user supplied
'404':
description: User not found
# request body documentation
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/User'
application/xml:
schema:
$ref: '#/components/schemas/User'
description: Updated user object
required: true
/echo: # path parameter in curly braces
post: # documentation for POST operation for this path
tags:
- Echo
summary: Echo test
description: Receive the exact message you've sent
operationId: echo
security:
- api_key: []
- basic_auth: []
responses:
'200':
description: OK
# document headers for this response
headers:
X-Rate-Limit: # Header name
description: calls per hour allowed by the user
schema: # Header schema
type: integer
format: int32
X-Expires-After:
$ref: '#/components/headers/ExpiresAfter'
content:
application/json:
schema:
type: string
examples:
response:
value: Hello world!
application/xml:
schema:
type: string
text/csv:
schema:
type: string
requestBody:
content:
application/json:
schema:
type: string
example: Hello world!
application/xml:
schema:
type: string
example: Hello world!
description: Echo payload
required: true
# An object to hold reusable parts that can be used across the definition
components:
schemas:
Email:
description: User email address
type: string
format: test
example: john.smith@example.com
User:
type: object
properties:
username:
description: User supplied username
type: string
minLength: 4
example: John78
firstName:
description: User first name
type: string
minLength: 1
example: John
lastName:
description: User last name
type: string
minLength: 1
example: Smith
email:
$ref: '#/components/schemas/Email'
headers:
ExpiresAfter:
description: date in UTC when token expires
schema:
type: string
format: date-time
# Security scheme definitions that can be used across the definition.
securitySchemes:
main_auth: # security definition name (you can name it as you want)
# the following options are specific to oauth2 type
type: oauth2 # authorization type, one of: oauth2, apiKey, http
flows:
implicit:
authorizationUrl: 'http://example.com/api/oauth/dialog'
scopes:
'read:users': read users info
'write:users': modify or remove users
api_key: # security definition name (you can name it as you want)
type: apiKey
# The following options are specific to apiKey type
in: header # Where API key will be passed: header or query
name: api_key # API key parameter name
basic_auth: # security definition name (you can name it as you want)
type: http
scheme: basic