README
Serverless OpenAPI(Swagger) Documentation Plugin
Generates OpenAPI 3.0.0(swagger) documentation from serverless configuration files.
This project is a fork from conqa/serverless-openapi-documentation OpenAPI and the configuration is inspired by the format used in serverless-aws-documentation.
Works well with ReDoc.
Usage
This plugin requires additional configuration to use, see the "Configuration" section for how to configure the plugin to generate documentation.
Below are the commandline options to run the generator:
serverless openapi generate [options]
Options
Plugin: ServerlessOpenAPIDocumentation
openapi generate ...................... Generate OpenAPI v3 Documentation
--output / -o ...................... Output file location [default: openapi.yml|json]
--format / -f ...................... OpenAPI file format (yml|json) [default: yml]
--indent / -i ...................... File indentation in spaces [default: 2]
--help / -h ...................... Help
Configuration
To configure this plugin to generate valid OpenAPI documentation there are two places you'll need to modify in your serverless.yml
file, the custom
variables section and the http
event section for each given function in your service.
This plugin is compatible with the same documentation configuration structure in serverless-aws-documentation and can run beside it.
The custom
section of your serverless.yml
can be configured as below:
custom:
documentation:
version: '1'
title: 'My API'
description: 'This is my API'
securitySchemes: {}
security: {}
models: {}
These configurations can be quite verbose; you can separate it out into it's own file, such as serverless.doc.yml
as below:
custom:
documentation: ${file(serverless.doc.yml):documentation}
functions:
myFunc:
events:
- http:
path: getStuff
method: get
documentation: ${file(serverless.doc.yml):endpoints.myFunc}
For more info on serverless.yml
syntax, see their docs.
Models
Models contain additional information that you can use to define schemas for endpoints. You must define the content type for each schema that you provide in the models.
The required directives for the models section are as follow:
name
: the name of the schemadescription
: a description of the schemacontentType
: the content type of the described request/response (ie.application/json
orapplication/xml
).schema
: The JSON Schema (website) that describes the model. You can either:- use inline
YAML
to define these - use serverless' functionality to merge in external schema file
- specify a path to json schema in which case if you reuse some types in multiple schemas - they will be included in resulting components once instead of duplicated for each referencing schema
- use inline
custom:
documentation:
models:
- name: "PutDocumentRequest"
description: "Inline schema example"
contentType: "application/json"
schema:
$schema: "http://json-schema.org/draft-04/schema#"
properties:
SomeObject:
type: "object"
properties:
SomeAttribute:
type: "string"
- name: "PutDocumentResponse"
description: "External file merge example"
contentType: "application/json"
schema: ${file(models/PutDocumentResponse.json)}
- name: "ErrorResponse"
description: "Path to a schema example"
contentType: "application/json"
schema: models/ErrorResponse.json
Functions
To define the documentation for a given function event, you need to create a documentation
attribute for your http event in your serverless.yml
file.
The documentation
section of the event configuration can contain the following attributes:
summary
: a short description of the methoddescription
: a detailed description of the methodtags
: an array of tags for this eventdeprecated
: boolean indicator that indicates clients should migrate away from this functionrequestBody
: contains description of the requestdescription
: a description of the request body
requestModels
: a list of models to describe the request bodies (see requestModels below)queryParams
: a list of query parameters (see queryParams below)pathParams
: a list of path parameters (see pathParams below)cookieParams
: a list of cookie parameters (see cookieParams below)methodResponses
: an array of response models and applicable status codesstatusCode
: applicable http status code (ie. 200/404/500 etc.)responseBody
: contains description of the responsedescription
: a description of the body response
responseHeaders
: a list of response headers (see responseHeaders below)responseModels
: a list of models to describe the request bodies (see responseModels below) for eachContent-Type
functions:
createUser:
handler: "handler.create"
events:
- http:
path: "create"
method: "post"
documentation:
summary: "Create User"
description: "Creates a user and then sends a generated password email"
requestBody:
description: "A user information object"
requestModels:
application/json: "PutDocumentRequest"
pathParams:
- name: "username"
description: "The username for a user to create"
schema:
type: "string"
pattern: "^[-a-z0-9_]+