Release 6.0

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)

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)

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.
 

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"
   },