1.0.9 • Published 5 years ago
serverless-openapi-generator
Licence
MIT
Version
1.0.9
Deps
2
Size
21 kB
Vulns
0
Weekly
0
Serverless OpenAPI Generator
A simple OpenAPI 3 definition generator for Serverless projects that follows the OpenAPI specification structure.
Usage
Install
npm install serverless-openapi --save-dev
Configuration
Add this plugin to the plugins section of your serverless.yml file.
plugins:
- serverless-openapi
Generating a defintion file
serverless openapi
Command Line Options
| Name | Command | Shortcut | Type | Required? | Description | Default |
|---|---|---|---|---|---|---|
| Output File Location | --output |
-o |
string |
Optional | The output file location | openapi.yml |
| OpenAPI Definition Format | --format |
-f |
json | yaml |
Optional | The format of the OpenAPI definition file. | yaml |
Separating definitions into their own file
OpenAPI defintions can get quite verbose. You can break these out into their own file, such as severerless.openapi.yml and then import them like such:
custom:
openapi: ${file(serverless.openapi.yml):openapi}
Sample Definitions
This plugin parses your serverless.yml file and extracts info and components defintions from custom.openapi, paths and HTTP methods from functions.events.http, and path definitions functions.events.http.openapi. It maintains the OpenAPI specification structure.
Openapi Field
custom:
openapi:
openapi: '3.0.3' # The version of OpenAPI you want to validate against
Info Field
custom:
openapi:
title: Sample Pet Store App
description: This is a sample server for a pet store.
termsOfService: http://example.com/terms/
contact:
name: API Support
url: http://www.example.com/support
email: support@example.com
license:
name: Apache 2.0
url: https://www.apache.org/licenses/LICENSE-2.0.html
version: 1.0.1
Servers Field
custom:
openapi:
servers:
- url: https://development.gigantic-server.com/v1
description: Development server
- url: https://staging.gigantic-server.com/v1
description: Staging server
- url: https://api.gigantic-server.com/v1
description: Production server
Components Field
Schemas Field with Serverless File Import
custom:
openapi:
components:
schemas:
ErrorResponse: ${file(schemas/Error.json)}
Schemas Field with Schema Reference
custom:
openapi:
components:
schemas:
ErrorResponse:
$ref: '#/components/schemas/ErrorResponse'
Security Schemes
custom:
openapi:
components:
securitySchemes:
PetAuth:
type: oauth2
flows:
implicit:
authorizationUrl: https://example.com/api/oauth/dialog
scopes:
write:pets: modify pets in your account
read:pets: read your pets
authorizationCode:
authorizationUrl: https://example.com/api/oauth/dialog
tokenUrl: https://example.com/api/oauth/token
scopes:
write:pets: modify pets in your account
read:pets: read your pets
Security Field
custom:
openapi:
security:
- PetAuth:
- read:pets
- write:pets
Paths Field (Function Definitions)
functions:
RetrievePets:
name: RetrievePets-Dev
events:
- http:
method: get
path: /pets
openapi:
summary: Retrieve pets
description: Retrieves pets
tags:
- Pets
security:
- PetAuth:
- read:pets
responses:
'200':
description: An API Query response with pets
content:
application/json:
schema:
$ref: '#/components/schemas/RetrievePetsResponse'
'400':
description: An invalid request error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'401':
description: An unauthorized error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'500':
description: An unknown error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'