diff --git a/README.md b/README.md
index b57e9afd3..666ec29cf 100644
--- a/README.md
+++ b/README.md
@@ -5,9 +5,12 @@
 # swagger-php
 
 Generate interactive [OpenAPI](https://www.openapis.org) documentation for your RESTful API using
-[doctrine annotations](https://www.doctrine-project.org/projects/annotations.html) (optional as of version 4.8; if required the `doctrine/annotations` library must be installed in addition to swagger.php).
+[doctrine annotations](https://www.doctrine-project.org/projects/annotations.html) (**optional as of version 4.8**; if required the `doctrine/annotations` library must be installed in addition to swagger.php).
 or [PHP attributes](https://www.php.net/manual/en/language.attributes.overview.php).
 
+⚠️ `doctrine/annotations` is going to be deprecated in the future, so wherever
+possible attributes should be used.
+
 For a full list of supported annotations, please have look at the [`OpenApi\Annotations` namespace](src/Annotations) or the [documentation website](https://zircote.github.io/swagger-php/guide/annotations.html).
 
 ## Features
diff --git a/docs/index.md b/docs/index.md
index e84a4cbe0..c2380d4ed 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -20,7 +20,10 @@ features:
 
 ### 2. Update your code
 
-Add `swagger-php` attributes or annotations to your source code.
+Add `swagger-php` attributes (or legacy annotations) to your source code.
+
+⚠️ `doctrine/annotations` is going to be deprecated in the future, so wherever
+possible attributes should be used.
 
 <codeblock id="minimal">
   <template v-slot:at>
@@ -53,4 +56,5 @@ Use an OpenAPI tool like [Swagger UI ](https://swagger.io/tools/swagger-ui/) to
 - [OpenApi Specification](https://spec.openapis.org/oas/v3.1.0.html)
 - [Learn by example](https://github.com/zircote/swagger-php/tree/master/Examples)
 - [Related projects](related-projects.md)
-- [Swagger-php 2.x documentation](https://github.com/zircote/swagger-php/tree/2.x/docs)
+- [swagger-php 2.x documentation](https://github.com/zircote/swagger-php/tree/2.x/docs)
+- [swagger-php 3.x documentation](https://github.com/zircote/swagger-php/tree/3.x/docs)
diff --git a/src/Generator.php b/src/Generator.php
index ab804aaf4..b9b2aa2ab 100644
--- a/src/Generator.php
+++ b/src/Generator.php
@@ -176,7 +176,7 @@ public function setNamespaces(?array $namespaces): Generator
 
     public function getAnalyser(): AnalyserInterface
     {
-        $this->analyser = $this->analyser ?: new ReflectionAnalyser([new DocBlockAnnotationFactory(), new AttributeAnnotationFactory()]);
+        $this->analyser = $this->analyser ?: new ReflectionAnalyser([new AttributeAnnotationFactory(), new DocBlockAnnotationFactory()]);
         $this->analyser->setGenerator($this);
 
         return $this->analyser;