From 82b0732a8f394987b615ceb40f140f940a0b5fcb Mon Sep 17 00:00:00 2001 From: Alex Lapa Date: Thu, 9 May 2019 10:54:27 +1200 Subject: [PATCH 1/2] Updating readme --- README.md | 42 ++++++++++++++++++++++++------------------ 1 file changed, 24 insertions(+), 18 deletions(-) diff --git a/README.md b/README.md index 1ba5c61..5850fdf 100644 --- a/README.md +++ b/README.md @@ -1,12 +1,11 @@ # Serverless OpenAPI Documentation Plugin -[![NPM](https://img.shields.io/npm/v/serverless-openapi-documentation.svg)](https://npmjs.org/packages/serverless-openapi-documentation/) -[![Travis CI](https://img.shields.io/travis/temando/serverless-openapi-documentation.svg)](https://travis-ci.org/temando/serverless-openapi-documentation) -[![JavaScript Style Guide](https://img.shields.io/badge/code_style-standard-brightgreen.svg)](https://standardjs.com) +[![NPM](https://img.shields.io/npm/v/@conqa/serverless-openapi-documentation.svg)](https://npmjs.org/packages/@conqa/serverless-openapi-documentation/) +[![Travis CI](https://img.shields.io/travis/conqa/serverless-openapi-documentation.svg)](https://travis-ci.org/conqa/serverless-openapi-documentation) Generates [**OpenAPI 3.0.0**](https://github.com/OAI/OpenAPI-Specification/blob/3.0.0/versions/3.0.0.md) documentation from serverless configuration files. OpenAPI is formerly known as Swagger. The configuration is inspired by the format used in [serverless-aws-documentation](https://www.npmjs.com/package/serverless-aws-documentation). -Works well with [Lincoln OpenAPI Renderer](https://github.com/temando/open-api-renderer). +Works well with [ReDoc](https://github.com/Rebilly/ReDoc). --- @@ -20,7 +19,7 @@ Works well with [Lincoln OpenAPI Renderer](https://github.com/temando/open-api-r - [`cookieParams`](#cookieparams) - [`requestModels`](#requestmodels) - [`methodResponses`](#methodresponses) -- [Example Configuration](#example-configuration) +- [Example configuration](#example-configuration) - [Install](#install) --- @@ -60,6 +59,10 @@ custom: 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: {} ``` @@ -89,22 +92,17 @@ The *required* 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` or `application/xml`). -* `schema`: The JSON Schema ([website](http://json-schema.org/)) that describes the model. You can either use inline `YAML` to define these, or refer to an external schema file as below +* `schema`: The JSON Schema ([website](http://json-schema.org/)) 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 ```yml custom: documentation: models: - - name: "ErrorResponse" - description: "This is an error" - contentType: "application/json" - schema: ${file(models/ErrorResponse.json)} - - name: "PutDocumentResponse" - description: "PUT Document response model (external reference example)" - contentType: "application/json" - schema: ${file(models/PutDocumentResponse.json)} - name: "PutDocumentRequest" - description: "PUT Document request model (inline example)" + description: "Inline schema example" contentType: "application/json" schema: $schema: "http://json-schema.org/draft-04/schema#" @@ -114,6 +112,14 @@ custom: 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 @@ -312,19 +318,19 @@ To add this plugin to your package.json: **Using npm:** ```bash -npm install serverless-openapi-documentation --save-dev +npm install @conqa/serverless-openapi-documentation --save-dev ``` **Using Yarn:** ```bash -yarn add serverless-openapi-documentation --dev +yarn add @conqa/serverless-openapi-documentation --dev ``` Next you need to add the plugin to the `plugins` section of your `serverless.yml` file. ```yml plugins: - - serverless-openapi-documentation + - @conqa/serverless-openapi-documentation ``` You can confirm the plugin is correctly installed by running: From 60087b6e612ac0ac0b554f728605fbf2cd33fd03 Mon Sep 17 00:00:00 2001 From: Alex Lapa Date: Thu, 9 May 2019 11:22:00 +1200 Subject: [PATCH 2/2] Updating changelog --- CHANGELOG.md | 35 ++++++++++++++++++++++++++++++++++- 1 file changed, 34 insertions(+), 1 deletion(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index aacc138..54f4260 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -5,7 +5,40 @@ All notable changes to this project will be documented in this file. The format is based on [Keep a Changelog](http://keepachangelog.com/en/1.0.0/) and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.html). +## [Unreleased] +### Added +- Support for securitySchemes and security #15 +- Support for servers #18 +- Support for schemas included by path with all $refs merged into components #7 +### Changed +- Convert project from Yarn to npm #5 +- Switch to eslint #8 +- Update Readme #19 + +## [1.0.4] - 2019-05-07 +### Fixed +- Fix issue with last release where the package was published from the root directory, not the build directory + +## [1.0.3] - 2019-05-07 +### Fixed +- Fix for requestBody and parameters #6 + +## [1.0.2] - 2019-05-03 +### Changed +- test tag publish + +## [1.0.1] - 2019-05-02 +### Changed +- test tag publish + +## [1.0.0] - 2019-05-02 +### Changed +- inital release after forking from temando/serverless-openapi-documentation + [Unreleased]: https://github.com/conqa/serverless-openapi-documentation/compare/v1.0.4...HEAD [1.0.4]: https://github.com/conqa/serverless-openapi-documentation/compare/v1.0.3...v1.0.4 -[1.0.3]: https://github.com/conqa/serverless-openapi-documentation/tree/v1.0.3 \ No newline at end of file +[1.0.3]: https://github.com/conqa/serverless-openapi-documentation/compare/v1.0.2...v1.0.3 +[1.0.2]: https://github.com/conqa/serverless-openapi-documentation/compare/v1.0.1...v1.0.2 +[1.0.1]: https://github.com/conqa/serverless-openapi-documentation/compare/v1.0.0...v1.0.1 +[1.0.0]: https://github.com/conqa/serverless-openapi-documentation/tree/v1.0.0