@finn.auto/sls-openapi-doc-generator
v2.1.3
Published
Serverless 1.0 plugin to generate OpenAPI V3 documentation from serverless configuration
Downloads
7
Readme
Serverless OpenAPI Documentation Plugin
Generates OpenAPI 3.0.0 documentation from serverless configuration files. OpenAPI is formerly known as Swagger. 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'
# https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md#securitySchemeObject
securitySchemes: {}
# https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md#security-requirement-object
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:
serverless-offline: # local testing plugin
httpPort: 8000
lambdaPort: 8002
noPrependStageInUrl: true # important for local docs routing working correctly
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_]+$"
queryParams:
- name: "membershipType"
description: "The user's Membership Type"
schema:
type: "string"
enum:
- "premium"
- "standard"
cookieParams:
- name: "SessionId"
description: "A Session ID variable"
schema:
type: "string"
methodResponses:
- statusCode: 201
responseBody:
description: "A user object along with generated API Keys"
responseModels:
application/json: "PutDocumentResponse"
- statusCode: 500
responseBody:
description: "An error message when creating a new user"
responseModels:
application/json: "ErrorResponse"
queryParams
Query parameters can be described as follow:
name
: the name of the query variabledescription
: a description of the query variablerequired
: whether the query parameter is mandatory (boolean)schema
: JSON schema (inline or file)
queryParams:
- name: "filter"
description: "The filter parameter"
required: true
schema:
type: "string"
pathParams
They get derived form the event path thus do not need to be passed explicitly. Path parameters can be described as follows:
name
: the name of the query variabledescription
: a description of the query variableschema
: JSON schema (inline or file)
pathParams:
- name: "usernameId"
description: "The usernameId parameter"
schema:
type: "string"
cookieParams
Cookie parameters can be described as follows:
name
: the name of the query variabledescription
: a description of the query variablerequired
: whether the query parameter is mandatory (boolean)schema
: JSON schema (inline or file)
cookieParams:
- name: "sessionId"
description: "The sessionId parameter"
required: true
schema:
type: "string"
requestModels
The requestModels
property allows you to define models for the HTTP Request of the function event. You can define a different model for each different Content-Type
. You can define a reference to the relevant request model named in the models
section of your configuration (see Defining Models section).
requestModels:
application/json: "CreateRequest"
application/xml: "CreateRequestXML"
methodResponses
You can define the response schemas by defining properties for your function event.
For an example of a methodResponses
configuration for an event see below:
methodResponse:
- statusCode: 200
responseHeaders:
- name: "Content-Type"
description: "Content Type header"
schema:
type: "string"
responseModels:
application/json: "CreateResponse"
application/xml: "CreateResponseXML"
responseModels
The responseModels
property allows you to define models for the HTTP Response of the function event. You can define a different model for each different Content-Type
. You can define a reference to the relevant response model named in the models
section of your configuration (see Defining Models section).
responseModels:
application/json: "CreateResponse"
application/xml: "CreateResponseXML"
responseHeaders
and requestHeaders
The responseHeaders/requestHeaders
section of the configuration allows you to define the HTTP headers for the function event.
The attributes for a header are as follow:
name
: the name of the HTTP Headerdescription
: a description of the HTTP Headerschema
: JSON schema (inline or file)
responseHeaders:
- name: "Content-Type"
description: "Content Type header"
schema:
type: "string"
requestHeaders:
- name: "Content-Type"
description: "Content Type header"
schema:
type: "string"
Example configuration
Please view the example serverless.yml.
Install
This plugin works for Serverless 1.x and up. Serverless 0.5 is not supported.
To add this plugin to your package.json:
Using npm:
npm install @finn.auto/sls-openapi-doc-generator --save-dev
Using Yarn:
yarn add @finn.auto/sls-openapi-doc-generator --dev
Next you need to add the plugin to the plugins
section of your serverless.yml
file.
plugins:
- @finn.auto/sls-openapi-doc-generator
It should return ServerlessOpenAPIDocumentation
as one of the plugins on the list.
Note: Add this plugin after
serverless-offline
to prevent issues withString.replaceAll
being overridden incorrectly.
Test
All you need to do is to run the following command
yarn test:docjson
check if the command was executed without any errors and the result looks the way you want it.
Test case runs automatically on the test/css folder, thus in case you want to include your own project both
prepareTests.bash
script and test:docjson
need to be adjusted accordingly.
To see the generated docs preview on localhost run
cd test/css && sls offline && cd ../..
License
MIT