Automated update of fixed-spotify-open-api.yml (#325)

* Automated update of fixed-spotify-open-api.yml

* fix: add deprecation notice

Author: sonallux

spotify-web-api-java-generator/fixed-spotify-open-api.yml

@@ -8,7 +8,7 @@ info:
     The base URI for all Web API requests is `https://api.spotify.com/v1`.
 
     Need help? See our <a href="https://developer.spotify.com/documentation/web-api/guides/">Web API guides</a> for more information, or visit the <a href="https://community.spotify.com/t5/Spotify-for-Developers/bd-p/Spotify_Developer">Spotify for Developers community forum</a> to ask questions and connect with other developers.
-  version: 2024.11.2
+  version: 2024.12.23
   title: Spotify Web API with fixes and improvements from sonallux
   termsOfService: https://developer.spotify.com/terms/
   contact:
@@ -211,6 +211,7 @@ paths:
       - oauth_2_0: []
   /artists/{id}/related-artists:
     get:
+      deprecated: true
       tags:
       - Artists
       operationId: get-an-artists-related-artists
@@ -1830,6 +1831,7 @@ paths:
         - playlist-modify-private
   /browse/featured-playlists:
     get:
+      deprecated: true
       tags:
       - Playlists
       operationId: get-featured-playlists
@@ -1933,6 +1935,7 @@ paths:
       - oauth_2_0: []
   /browse/categories/{category_id}/playlists:
     get:
+      deprecated: true
       tags:
       - Playlists
       - Categories
@@ -2195,7 +2198,7 @@ paths:
                   items:
                     type: string
       responses:
-        "200":
+        "204":
           description: Artist or user unfollowed
         "401":
           $ref: "#/components/responses/Unauthorized"
@@ -2285,6 +2288,7 @@ paths:
       - oauth_2_0: []
   /audio-features:
     get:
+      deprecated: true
       tags:
       - Tracks
       operationId: get-several-audio-features
@@ -2316,6 +2320,7 @@ paths:
       - oauth_2_0: []
   /audio-features/{id}:
     get:
+      deprecated: true
       tags:
       - Tracks
       operationId: get-audio-features
@@ -2347,6 +2352,7 @@ paths:
       - oauth_2_0: []
   /audio-analysis/{id}:
     get:
+      deprecated: true
       tags:
       - Tracks
       operationId: get-audio-analysis
@@ -2378,6 +2384,7 @@ paths:
       - oauth_2_0: []
   /recommendations:
     get:
+      deprecated: true
       tags:
       - Tracks
       operationId: get-recommendations
@@ -2836,6 +2843,7 @@ paths:
       - oauth_2_0: []
   /recommendations/available-genre-seeds:
     get:
+      deprecated: true
       tags:
       - Genres
       operationId: get-recommendation-genres
@@ -5048,6 +5056,7 @@ components:
           type: string
           description: The name of the track.
         preview_url:
+          deprecated: true
           type: string
           nullable: true
           description: |
@@ -5781,6 +5790,7 @@ components:
           description: |
             The popularity of the track. The value will be between 0 and 100, with 100 being the most popular.<br/>The popularity of a track is a value between 0 and 100, with 100 being the most popular. The popularity is calculated by algorithm and is based, in the most part, on the total number of plays the track has had and how recent those plays are.<br/>Generally speaking, songs that are being played a lot now will have a higher popularity than songs that were played a lot in the past. Duplicate tracks (e.g. the same track from a single and an album) are rated independently. Artist and album popularity is derived mathematically from track popularity. _**Note**: the popularity value may lag actual popularity by a few days: the value is not updated in real time._
         preview_url:
+          deprecated: true
           type: string
           nullable: true
           description: |
@@ -5844,6 +5854,7 @@ components:
       - uri
       properties:
         audio_preview_url:
+          deprecated: true
           type: string
           nullable: true
           example: https://p.scdn.co/mp3-preview/2f37da1d4221f40b9d1a98cd191f4d6f1646ad17
@@ -6383,6 +6394,7 @@ components:
       - uri
       properties:
         audio_preview_url:
+          deprecated: true
           type: string
           nullable: true
           example: https://p.scdn.co/mp3-preview/2f37da1d4221f40b9d1a98cd191f4d6f1646ad17
@@ -6535,11 +6547,10 @@ components:
             type: array
             items:
               type: string
-            example:
-            - Egg punk
-            - Noise rock
+            deprecated: true
+            example: []
             description: |
-              A list of the genres the album is associated with. If not yet classified, the array is empty.
+              **Deprecated** The array is always empty.
           label:
             type: string
             description: |

spotify-web-api-java-generator/src/main/java/de/sonallux/spotify/generator/java/generators/ApiGenerator.java

@@ -52,6 +52,7 @@ private Map<String, Object> buildEndpointContext(ApiEndpoint endpoint, JavaPacka
         var methodName = CaseFormat.LOWER_HYPHEN.to(CaseFormat.LOWER_CAMEL, endpoint.getEndpointId());
         context.put("methodName", methodName);
         context.put("name", endpoint.getName());
+        context.put("deprecated", endpoint.isDeprecated());
         context.put("description", Markdown2Html.convertToSingleLine(endpoint.getDescription()));
         context.put("requestBuilder", JavaUtils.getEndpointRequestBuilderName(endpoint.getEndpointId()));
 
@@ -77,6 +78,7 @@ private List<ApiEndpoint.Parameter> generateEndpointRequest(ApiEndpoint endpoint
         var context = new HashMap<String, Object>();
         context.put("package", javaPackage.getName());
         context.put("name", endpoint.getName() + " request");
+        context.put("deprecated", endpoint.isDeprecated());
         context.put("className", className);
         context.put("httpMethod", endpoint.getHttpMethod());
         context.put("path", endpoint.getPath());

spotify-web-api-java-generator/src/main/java/de/sonallux/spotify/generator/java/generators/EndpointSplitter.java

@@ -16,29 +16,31 @@ public static void splitEndpoints(SpotifyWebApi spotifyWebApi) {
         }
 
         var reorderEndpoint = new ApiEndpoint(
-                "reorder-playlists-tracks",
-                "Reorder Playlist Items",
-                "Reorder items in a playlist",
-                endpoint.getPath(),
-                endpoint.getHttpMethod(),
-                endpoint.getResponseType(),
-                endpoint.getResponseDescription(),
-                endpoint.getScopes()
+            "reorder-playlists-tracks",
+            "Reorder Playlist Items",
+            "Reorder items in a playlist",
+            endpoint.getPath(),
+            endpoint.getHttpMethod(),
+            endpoint.getResponseType(),
+            endpoint.getResponseDescription(),
+            endpoint.getScopes(),
+            false
         );
         reorderEndpoint.addPathParameter(endpoint.getRequiredPathParameters().get(0), true);
         endpoint.getOptionalBodyParameters().stream()
                 .filter(param -> List.of("range_start", "insert_before", "range_length", "snapshot_id").contains(param.getName()))
                 .forEach(param -> reorderEndpoint.addBodyParameter(param, List.of("range_start", "insert_before").contains(param.getName())));
 
         var replaceEndpoint = new ApiEndpoint(
-                "replace-playlists-tracks",
-                "Replace Playlist Items",
-                "Replacing items in a playlist will overwrite its existing items. This operation can be used for replacing or clearing items in a playlist.",
-                endpoint.getPath(),
-                endpoint.getHttpMethod(),
-                endpoint.getResponseType(),
-                endpoint.getResponseDescription(),
-                endpoint.getScopes()
+            "replace-playlists-tracks",
+            "Replace Playlist Items",
+            "Replacing items in a playlist will overwrite its existing items. This operation can be used for replacing or clearing items in a playlist.",
+            endpoint.getPath(),
+            endpoint.getHttpMethod(),
+            endpoint.getResponseType(),
+            endpoint.getResponseDescription(),
+            endpoint.getScopes(),
+            false
         );
         replaceEndpoint.addPathParameter(endpoint.getRequiredPathParameters().get(0), true);
         endpoint.getOptionalQueryParameters().stream()

spotify-web-api-java-generator/src/main/java/de/sonallux/spotify/generator/java/generators/ObjectModelCreator.java

@@ -48,8 +48,9 @@ private void visitOperation(ApiCategory category, PathItem.HttpMethod method, St
         var responseType = getResponseType(response);
         var responseDescription = generationContext.resolveResponse(response).getDescription();
         var scopes = JavaUtils.getScopes(operation);
+        var deprecated = operation.getDeprecated() != null && operation.getDeprecated();
 
-        var endpoint = new ApiEndpoint(endpointId, name, description, path, httpMethod, responseType, responseDescription, scopes);
+        var endpoint = new ApiEndpoint(endpointId, name, description, path, httpMethod, responseType, responseDescription, scopes, deprecated);
         category.addEndpoint(endpoint);
 
         if (operation.getParameters() != null) {

spotify-web-api-java-generator/src/main/java/de/sonallux/spotify/generator/java/model/ApiEndpoint.java

@@ -18,6 +18,7 @@ public class ApiEndpoint {
     private final String responseType;
     private final String responseDescription;
     private final List<String> scopes;
+    private final boolean deprecated;
     private final List<Parameter> requiredPathParameters;
     private final List<Parameter> requiredQueryParameters;
     private final List<Parameter> requiredBodyParameters;
@@ -26,7 +27,7 @@ public class ApiEndpoint {
     private final List<Parameter> optionalBodyParameters;
     private RawBodyParameter rawBodyParameter = null;
 
-    public ApiEndpoint(String endpointId, String name, String description, String path, String httpMethod, String responseType, String responseDescription, List<String> scopes) {
+    public ApiEndpoint(String endpointId, String name, String description, String path, String httpMethod, String responseType, String responseDescription, List<String> scopes, boolean deprecated) {
         this.endpointId = endpointId;
         this.name = name;
         this.description = description;
@@ -35,6 +36,7 @@ public ApiEndpoint(String endpointId, String name, String description, String pa
         this.responseType = responseType;
         this.responseDescription = responseDescription;
         this.scopes = scopes;
+        this.deprecated = deprecated;
         this.requiredPathParameters = new ArrayList<>();
         this.requiredQueryParameters = new ArrayList<>();
         this.requiredBodyParameters = new ArrayList<>();

spotify-web-api-java-generator/src/main/resources/templates/api.mustache

@@ -19,6 +19,9 @@ public class {{className}} {
      * {{.}}
     {{/javaDocParameters}}
      * @return a {@link {{requestBuilder}}} object to build and execute the request
+    {{#deprecated}}
+     * @deprecated see <a href="https://developer.spotify.com/blog/2024-11-27-changes-to-the-web-api">this blog post from Spotify</a>
+    {{/deprecated}}
      */
     public {{requestBuilder}} {{methodName}}({{requiredParameters}}) {
         return new {{requestBuilder}}({{arguments}});

spotify-web-api-java-generator/src/main/resources/templates/request.mustache

@@ -18,6 +18,9 @@ import de.sonallux.spotify.api.models.*;
 {{#responseDescription}}
  * {{.}}
 {{/responseDescription}}
+{{#deprecated}}
+ * @deprecated see <a href="https://developer.spotify.com/blog/2024-11-27-changes-to-the-web-api">this blog post from Spotify</a>
+{{/deprecated}}
  */
 public class {{className}} {
     private static final TypeReference<{{responseType}}> RESPONSE_TYPE = new TypeReference<>() {};

spotify-web-api-java/src/main/generated/de/sonallux/spotify/api/apis/ArtistsApi.java

@@ -36,6 +36,7 @@ public GetArtistsAlbumsRequest getArtistsAlbums(String id) {
      * <p>Get Spotify catalog information about artists similar to a given artist. Similarity is based on analysis of the Spotify community's listening history.</p>
      * @param id <p>The <a href="https://developer.spotify.com/documentation/web-api/concepts/spotify-uris-ids">Spotify ID</a> of the artist.</p>
      * @return a {@link GetArtistsRelatedArtistsRequest} object to build and execute the request
+     * @deprecated see <a href="https://developer.spotify.com/blog/2024-11-27-changes-to-the-web-api">this blog post from Spotify</a>
      */
     public GetArtistsRelatedArtistsRequest getArtistsRelatedArtists(String id) {
         return new GetArtistsRelatedArtistsRequest(apiClient, id);

spotify-web-api-java/src/main/generated/de/sonallux/spotify/api/apis/GenresApi.java

@@ -15,6 +15,7 @@ public class GenresApi {
      * <h4>Get Available Genre Seeds</h4>
      * <p>Retrieve a list of available genres seed parameter values for <a href="https://developer.spotify.com/documentation/web-api/reference/get-recommendations">recommendations</a>.</p>
      * @return a {@link GetRecommendationGenresRequest} object to build and execute the request
+     * @deprecated see <a href="https://developer.spotify.com/blog/2024-11-27-changes-to-the-web-api">this blog post from Spotify</a>
      */
     public GetRecommendationGenresRequest getRecommendationGenres() {
         return new GetRecommendationGenresRequest(apiClient);

spotify-web-api-java/src/main/generated/de/sonallux/spotify/api/apis/PlaylistsApi.java

@@ -48,6 +48,7 @@ public CreatePlaylistRequest createPlaylist(String userId, String name) {
      * <p>Get a list of Spotify playlists tagged with a particular category.</p>
      * @param categoryId <p>The <a href="https://developer.spotify.com/documentation/web-api/concepts/spotify-uris-ids">Spotify category ID</a> for the category.</p>
      * @return a {@link GetCategoriesPlaylistsRequest} object to build and execute the request
+     * @deprecated see <a href="https://developer.spotify.com/blog/2024-11-27-changes-to-the-web-api">this blog post from Spotify</a>
      */
     public GetCategoriesPlaylistsRequest getCategoriesPlaylists(String categoryId) {
         return new GetCategoriesPlaylistsRequest(apiClient, categoryId);
@@ -57,6 +58,7 @@ public GetCategoriesPlaylistsRequest getCategoriesPlaylists(String categoryId) {
      * <h4>Get Featured Playlists</h4>
      * <p>Get a list of Spotify featured playlists (shown, for example, on a Spotify player's 'Browse' tab).</p>
      * @return a {@link GetFeaturedPlaylistsRequest} object to build and execute the request
+     * @deprecated see <a href="https://developer.spotify.com/blog/2024-11-27-changes-to-the-web-api">this blog post from Spotify</a>
      */
     public GetFeaturedPlaylistsRequest getFeaturedPlaylists() {
         return new GetFeaturedPlaylistsRequest(apiClient);