Update documentation

docs/GETTING-STARTED.md

@@ -7,7 +7,6 @@ const swaggerJsdoc = require('swagger-jsdoc');
 
 const options = {
   swaggerDefinition: {
-    openapi: '3.0.0',
     info: {
       title: 'Hello World',
       version: '1.0.0',
@@ -24,6 +23,31 @@ const swaggerSpecification = swaggerJsdoc(options);
 
 Use any of the [swagger tools](https://swagger.io/tools/) to get the benefits of your `swaggerSpecification`.
 
+## Specification version
+
+`swagger-jsdoc` was created in 2015. The OpenAPI as a concept did not exist, and thus the naming of the package itself.
+
+The default target specification is 2.0. This provides backwards compatibility for many APIs written in the last couple of years.
+
+In order to create a specification compatibile with 3.0 or higher, i.e. the so called OpenAPI, set this information in the `swaggerDefinition`:
+
+```diff
+const swaggerJsdoc = require('swagger-jsdoc');
+
+const options = {
+  swaggerDefinition: {
++   openapi: '3.0.0',
+    info: {
+      title: 'Hello World',
+      version: '1.0.0',
+    },
+  },
+  apis: ['./src/routes*.js'],
+};
+
+const swaggerSpecification = swaggerJsdoc(options);
+```
+
 ## Annotating source code
 
 Place `@swagger` or `@openapi` on top of YAML-formatted specification parts:
@@ -53,6 +77,8 @@ 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.
@@ -130,8 +156,6 @@ app.post('/users', (req, res) => {
 });
 ```
 
-Keep in mind that since v3 of the specification, you can use [components](https://swagger.io/docs/specification/components/) in order to define and reuse resources.
-
 ## Using YAML
 
 It's possible to source parts of your specification through YAML files.