From d2965dbf919956010bcc156e29fa086986e324e3 Mon Sep 17 00:00:00 2001 From: Kalin Chernev Date: Wed, 23 Dec 2020 10:24:46 +0100 Subject: [PATCH] Release 6.0 --- CHANGELOG.md | 6 +++ docs/GETTING-STARTED.md | 100 ++++++++-------------------------------- docs/TYPESCRIPT.md | 10 ++-- package.json | 2 +- 4 files changed, 33 insertions(+), 85 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 24cd25bc..917f8e51 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,11 @@ ## Change Log +### v6.0.0 (2020/12/23 09:24 +00:00) + +- [0d0be79](https://github.com/Surnet/swagger-jsdoc/commit/0d0be797263a6f95dd0efcc5386b37b8757f8ecb) Update documentation (@kalinchernev) +- [6db97e2](https://github.com/Surnet/swagger-jsdoc/commit/6db97e25832e0f94f87db9c5d5340122efe4f385) update changelog (@kalinchernev) +- [a72a91f](https://github.com/Surnet/swagger-jsdoc/commit/a72a91f6262172b0bb49f089039cc176f1564d6c) prepare rc5 (@kalinchernev) + ### v6.0.0-rc.5 (2020/12/16 08:56 +00:00) - [#235](https://github.com/Surnet/swagger-jsdoc/pull/235) feat: support x-webhooks (#235) (@kalinchernev) diff --git a/docs/GETTING-STARTED.md b/docs/GETTING-STARTED.md index ffabd2b3..eff6c378 100644 --- a/docs/GETTING-STARTED.md +++ b/docs/GETTING-STARTED.md @@ -75,87 +75,6 @@ app.post('/login', (req, res) => { }); ``` -## Re-using Model Definitions - -The examples below are targeting specification 2.0. Please keep in mind that since 3.x, you can use [components](https://swagger.io/docs/specification/components/) in order to define and reuse resources. - -A model may be the same for multiple endpoints: `POST`, `PUT` responses, etc. - -Duplicating parts of your code into multiple locations is error prone and requires more attention when maintaining your code base. To solve these, you can define a model and re-use it across multiple endpoints. You can also reference another model and add fields. - -```javascript -/** - * @swagger - * - * definitions: - * NewUser: - * type: object - * required: - * - username - * - password - * properties: - * username: - * type: string - * password: - * type: string - * format: password - * User: - * allOf: - * - $ref: '#/definitions/NewUser' - * - required: - * - id - * - properties: - * id: - * type: integer - * format: int64 - */ - -/** - * @swagger - * /users: - * get: - * description: Returns users - * produces: - * - application/json - * responses: - * 200: - * description: users - * schema: - * type: array - * items: - * $ref: '#/definitions/User' - */ -app.get('/users', (req, res) => { - // Your implementation logic comes here ... -}); - -/** - * @swagger - * - * /users: - * post: - * description: Creates a user - * produces: - * - application/json - * parameters: - * - name: user - * description: User object - * in: body - * required: true - * type: string - * schema: - * $ref: '#/definitions/NewUser' - * responses: - * 200: - * description: users - * schema: - * $ref: '#/definitions/User' - */ -app.post('/users', (req, res) => { - // Your implementation logic comes here ... -}); -``` - ## Using YAML It's possible to source parts of your specification through YAML files. @@ -202,3 +121,22 @@ Additional materials to inspire you: - [Agile documentation for your API-driven project](https://kalinchernev.github.io/agile-documentation-api-driven-project) - 21/01/2017 Suggestions for extending this helpful list are welcome! [Submit your article](https://github.com/Surnet/swagger-jsdoc/issues/new) + +## Examples + +Here's a list of example public open-source usages of the package: + +- [godaddy/gasket](https://github.com/godaddy/gasket) +- [godaddy/warehouse.ai-status-api](https://github.com/godaddy/warehouse.ai-status-api) +- [hana-developer-cli-tool-example](https://github.com/SAP-samples/hana-developer-cli-tool-example) +- [studiohyperdrive/api-docs](https://github.com/studiohyperdrive/api-docs) + +## Related projects + +- [godaddy/swagger-jsdoc-deref](https://github.com/godaddy/swagger-jsdoc-deref) +- [slanatech/swagger-stats](https://github.com/slanatech/swagger-stats) +- [weseek/growi](https://github.com/weseek/growi) +- [linagora/openpaas-esn](https://github.com/linagora/openpaas-esn) +- [Tiemma/sonic-express](https://github.com/Tiemma/sonic-express) +- [kevoj/nodetomic-api-swagger](https://github.com/kevoj/nodetomic-api-swagger) +- [node-express-mongoose-boilerplate](https://github.com/hagopj13/node-express-mongoose-boilerplate) diff --git a/docs/TYPESCRIPT.md b/docs/TYPESCRIPT.md index 810c6ea5..4f5708d5 100644 --- a/docs/TYPESCRIPT.md +++ b/docs/TYPESCRIPT.md @@ -1,12 +1,16 @@ # Typescript +## Types + +Please see `[@types/swagger-jsdoc](https://www.npmjs.com/package/@types/swagger-jsdoc)`. The package has been created and maintained by one of the original creators of `swagger-jsdoc` [drGrove](https://github.com/drGrove). + ## The library -It's currently written in Vanilla JavaScript compatible with Node.js 12 or higher. There are no compilation, transpilation or bundling steps. JSDoc comments and annotations have been maintained and published for intelligent editors. However, no types are managed or published. +It's currently written in Vanilla JavaScript compatible with Node.js 12 or higher. There are no compilation, transpilation or bundling steps. JSDoc comments and annotations have been maintained and published for intelligent editors. -With time, it's possible that the library transitions into this direction, however first step would be to [reuse existing annotations and generate declarations](https://humanwhocodes.com/snippets/2020/10/create-typescript-declarations-from-javascript-jsdoc/), and publishing them. It's worth trying a similar approach to our [peer project yaml](https://github.com/eemeli/yaml) and its types management before going directly to full rewrite and compilation. +No types definitions are managed or published from this repository. -## Re-using interfaces +## Re-using interfaces from source code `swagger-jsdoc` is only taking into account JSDoc comments and pure YAML files. The library does not work with source code at all: no reading, no parsing, no modifications. diff --git a/package.json b/package.json index de0726c2..e6ac4f54 100644 --- a/package.json +++ b/package.json @@ -1,7 +1,7 @@ { "name": "swagger-jsdoc", "description": "Generates swagger doc based on JSDoc", - "version": "6.0.0-rc.5", + "version": "6.0.0", "engines": { "node": ">=12.0.0" },