Init OpenAPI template
This commit is contained in:
commit
968a1d1e97
GPG key ID:
2C2C1C62A5388E82
1 changed files with 223 additions and 0 deletions
223
openapi.yml
Normal file
223
openapi.yml
Normal 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
|
||||
Loading…
Reference in a new issue