Repository files navigation

GeneratesOpenAPI 3.0.0 documentation from serverless configuration files. OpenAPI is formerly known as Swagger. The configuration is inspired by the format used inserverless-aws-documentation. This plugin takes overserverless-openapi-documentation, which was no longer maintained. It aims to provide improvements, and especially adds support for API Gateway'sHTTP Apis.

Works well withReDoc.

• Usage
  • Options
  • Configuration
    • Models
    • Functions
    • queryParams
    • pathParams
    • cookieParams
    • requestModels
    • methodResponses
• Example configuration
• Install

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]

Plugin: ServerlessOpenAPIDocumentationopenapi 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 indentationin spaces [default: 2]    --help / -h   ...................... Help

To configure this plugin to generate valid OpenAPI documentation there are two places you'll need to modify in yourserverless.yml file, thecustom variables section and thehttp event section for each given function in your service.

This plugin is compatible with the same documentation configuration structure inserverless-aws-documentation and can run beside it.

Thecustom section of yourserverless.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#securitySchemeObjectsecuritySchemes:{}# https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md#security-requirement-objectsecurity:{}models:{}

These configurations can be quite verbose; you can separate it out into it's own file, such asserverless.doc.yml as below:

custom:documentation:${file(serverless.doc.yml):documentation}functions:myFunc:events:      -http:path:getStuffmethod:getdocumentation:${file(serverless.doc.yml):endpoints.myFunc}

For more info onserverless.yml syntax, see their docs.

Models contain additional information that you can use to define schemas for endpoints. You must define thecontent type for each schema that you provide in the models.

Therequired directives for the models section are as follow:

• name: the name of the schema
• description: a description of the schema
• contentType: 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 inlineYAML 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

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

To define the documentation for a given function event, you need to create adocumentation attribute for your http event in yourserverless.yml file.

Thedocumentation section of the event configuration can contain the following attributes:

• summary: a short description of the method
• description: a detailed description of the method
• tags: an array of tags for this event
• deprecated: boolean indicator that indicates clients should migrate away from this function
• requestBody: contains description of the request
  • description: a description of the request body
• requestModels: a list of models to describe the request bodies (seerequestModels below)
• queryParams: a list of query parameters (seequeryParams below)
• pathParams: a list of path parameters (seepathParams below)
• cookieParams: a list of cookie parameters (seecookieParams below)
• methodResponses: an array of response models and applicable status codes
  • statusCode: applicable http status code (ie. 200/404/500 etc.)
  • responseBody: contains description of the response
    • description: a description of the body response
  • responseHeaders: a list of response headers (seeresponseHeaders below)
  • responseModels: a list of models to describe the request bodies (seeresponseModels 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:201responseBody:description:"A user object along with generated API Keys"responseModels:application/json:"PutDocumentResponse"            -statusCode:500responseBody:description:"An error message when creating a new user"responseModels:application/json:"ErrorResponse"

Query parameters can be described as follow:

• name: the name of the query variable
• description: a description of the query variable
• required: whether the query parameter is mandatory (boolean)
• schema: JSON schema (inline or file)

queryParams:  -name:"filter"description:"The filter parameter"required:trueschema:type:"string"

Path parameters can be described as follow:

• name: the name of the query variable
• description: a description of the query variable
• schema: JSON schema (inline or file)

pathParams:  -name:"usernameId"description:"The usernameId parameter"schema:type:"string"

Cookie parameters can be described as follow:

• name: the name of the query variable
• description: a description of the query variable
• required: whether the query parameter is mandatory (boolean)
• schema: JSON schema (inline or file)

cookieParams:  -name:"sessionId"description:"The sessionId parameter"required:trueschema:type:"string"

TherequestModels property allows you to define models for the HTTP Request of the function event. You can define a different model for each differentContent-Type. You can define a reference to the relevant request model named in themodels section of your configuration (seeDefining Models section).

requestModels:application/json:"CreateRequest"application/xml:"CreateRequestXML"

You can define the response schemas by defining properties for your function event.

For an example of amethodResponses configuration for an event see below:

methodResponse:  -statusCode:200responseHeaders:      -name:"Content-Type"description:"Content Type header"schema:type:"string"responseModels:application/json:"CreateResponse"application/xml:"CreateResponseXML"

TheresponseModels property allows you to define models for the HTTP Response of the function event. You can define a different model for each differentContent-Type. You can define a reference to the relevant response model named in themodels section of your configuration (seeDefining Models section).

responseModels:application/json:"CreateResponse"application/xml:"CreateResponseXML"

TheresponseHeaders/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 Header
• description: a description of the HTTP Header
• schema: 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"

Please view the exampleserverless.yml.

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 serverless-openapi --save-dev

Using Yarn:

yarn add serverless-openapi --dev

Next you need to add the plugin to theplugins section of yourserverless.yml file.

plugins:  -serverless-openapi

You can confirm the plugin is correctly installed by running:

serverless| grep -i"ServerlessOpenAPIDocumentation"

It should returnServerlessOpenAPIDocumentation as one of the plugins on the list.

Note: Add this pluginafterserverless-offline to prevent issues withString.replaceAll being overridden incorrectly.

MIT