Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Media list endpoints have incorrect OpenAPI (previously Swagger) example definitions #4885

Open
zackkrida opened this issue Sep 6, 2024 · 0 comments
Assignees
Labels
💻 aspect: code Concerns the software code in the repository 🤖 aspect: dx Concerns developers' experience with the codebase 🛠 goal: fix Bug fix 🟧 priority: high Stalls work on the project or its dependents 🧱 stack: api Related to the Django API 🐍 tech: python Involves Python

Comments

@zackkrida
Copy link
Member

zackkrida commented Sep 6, 2024

Description

Our API uses an OpenAPI schema, which can be viewed here:

https://api.openverse.org/v1/schema/?format=json (exclude the format param for yaml)

The examples for the /v1/audio/ and /v1/images/ paths are incorrect. This might be easiest to view locally like so:

http https://api.openverse.org/v1/schema/\?format\=json | jq '.paths."/v1/images/".get.responses."200".content."application/json".examples.OK'

{
  "result_count": 10000,
  "page_count": 20,
  "page_size": 20,
  "page": 1,
  "results": [
    {
      "result_count": 1, // See incorrectly duplicated, nested properties here
      "page_count": 1,
      "page_size": 20,
      "page": 1,
      "results": [
        {
          "id": "4bc43a04-ef46-4544-a0c1-63c63f56e276",
          "title": "Tree Bark Photo",
          "indexed_on": "2022-08-27T17:39:48Z",
		  ...

You'll see a similar result for the audio path at http https://api.openverse.org/v1/schema/\?format\=json | jq '.paths."/v1/audio/".get.responses."200".content."application/json".examples.OK'

As you can see, the results array is incorrectly nested. This is problematic because various codegen tools, API consumers, and so on rely on this spec for their own work, and inaccurate examples could prevent code generation and/or give false impressions of the workings of the API.

Additional context

@zackkrida zackkrida added 🟧 priority: high Stalls work on the project or its dependents 🛠 goal: fix Bug fix 💻 aspect: code Concerns the software code in the repository 🤖 aspect: dx Concerns developers' experience with the codebase 🧱 stack: api Related to the Django API python Pull requests that update Python code labels Sep 6, 2024
@dhruvkb dhruvkb self-assigned this Sep 23, 2024
@obulat obulat added 🐍 tech: python Involves Python and removed python Pull requests that update Python code labels Oct 1, 2024
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
💻 aspect: code Concerns the software code in the repository 🤖 aspect: dx Concerns developers' experience with the codebase 🛠 goal: fix Bug fix 🟧 priority: high Stalls work on the project or its dependents 🧱 stack: api Related to the Django API 🐍 tech: python Involves Python
Projects
Status: 📅 To Do
Development

No branches or pull requests

3 participants