starred/netbox
1
0
Fork 0
mirror of https://github.com/netbox-community/netbox.git synced 2026-01-11 21:10:29 +01:00
Code Issues 273 Packages Projects Releases 10 Wiki Activity

Inaccurate Swagger description for ipam_prefixes_available-ips_create API call #4185

New Issue
Closed
opened 2025-12-29 18:33:41 +01:00 by adam · 15 comments
adam commented 2025-12-29 18:33:41 +01:00
Owner
Copy Link

Originally created by @tomasherout on GitHub (Oct 12, 2020).

Originally assigned to: @DanSheps on GitHub.

Environment

  • Python version: 3.7.9
  • NetBox version: 2.9.6

Steps to Reproduce

  1. Look at Swagger definition of response for API call ipam_prefixes_available-ips_create:

image

=> it's described as returns array of objects AvailableIP type

  1. make POST request to /api/ipam/prefixes/${subnetID}/available-ips/ and look to response. It's inconsistent with definition:

2.1.: It should be return array, in the fact it returns object.
2.2: Family attribute is described as integer, but server returns object
2.3: It returns id, url, role and lot of other

Expected Behavior

Fixed Swagger description.

Observed Behavior

API call return object on top level:

image

It does not correspond to swagger definition of response. Object properties also does not match.

Originally created by @tomasherout on GitHub (Oct 12, 2020). Originally assigned to: @DanSheps on GitHub. ### Environment * Python version: 3.7.9 * NetBox version: 2.9.6 ### Steps to Reproduce 1. Look at Swagger definition of response for API call `ipam_prefixes_available-ips_create`: ![image](https://user-images.githubusercontent.com/43199492/95715794-b785d480-0c6a-11eb-8f27-6b8b9948fa76.png) => it's described as _returns array of objects AvailableIP type_ 2. make POST request to `/api/ipam/prefixes/${subnetID}/available-ips/` and look to response. It's inconsistent with definition: 2.1.: It should be return _array_, in the fact it returns _object_. 2.2: Family attribute is described as integer, but server returns object 2.3: It returns id, url, role and lot of other <!-- What did you expect to happen? --> ### Expected Behavior Fixed Swagger description. <!-- What happened instead? --> ### Observed Behavior API call return object on top level: ![image](https://user-images.githubusercontent.com/43199492/95716624-08e29380-0c6c-11eb-89e3-3feb87ead692.png) It does not correspond to swagger definition of response. Object properties also does not match.
adam added the type: bugstatus: accepted labels 2025-12-29 18:33:41 +01:00
adam closed this issue 2025-12-29 18:33:41 +01:00
adam commented 2025-12-29 18:33:41 +01:00
Author
Owner
Copy Link

@DanSheps commented on GitHub (Oct 13, 2020):

This serializer can report many or only a single address back.

We should probably return a consistent result no matter what, so I think this should return an array, but I will let others comment as well.

@DanSheps commented on GitHub (Oct 13, 2020): This serializer can report many or only a single address back. We should probably return a consistent result no matter what, so I think this should return an array, but I will let others comment as well.
adam commented 2025-12-29 18:33:42 +01:00
Author
Owner
Copy Link

@tomasherout commented on GitHub (Oct 14, 2020):

Create operation returns only one or nothgin. List operation only can return more ...

@tomasherout commented on GitHub (Oct 14, 2020): Create operation returns only one or nothgin. List operation only can return more ...
adam commented 2025-12-29 18:33:42 +01:00
Author
Owner
Copy Link

@jeremystretch commented on GitHub (Oct 14, 2020):

Create operation returns only one or nothgin. List operation only can return more ...

Yes, that's what Dan said. This is intentional behavior, provided for the convenience of the API consumer. I don't see a reason to change it.

@jeremystretch commented on GitHub (Oct 14, 2020): > Create operation returns only one or nothgin. List operation only can return more ... Yes, that's what Dan said. This is intentional behavior, provided for the convenience of the API consumer. I don't see a reason to change it.
adam commented 2025-12-29 18:33:42 +01:00
Author
Owner
Copy Link

@tomasherout commented on GitHub (Oct 15, 2020):

Incorrect Swagger description causes generated clients like https://github.com/netbox-community/go-netbox unusable for that call.

Can you say me in which case ipam_prefixes_available-ips_create (POST /api/ipam/prefixes/${prefix.id}/available-ips/) return array of objects with fields family, address, VRF?

@tomasherout commented on GitHub (Oct 15, 2020): Incorrect Swagger description causes generated clients like https://github.com/netbox-community/go-netbox unusable for that call. Can you say me in which case ipam_prefixes_available-ips_create (**POST** /api/ipam/prefixes/${prefix.id}/available-ips/) return array of objects with fields family, address, VRF?
adam commented 2025-12-29 18:33:42 +01:00
Author
Owner
Copy Link

@jeremystretch commented on GitHub (Oct 15, 2020):

The relevant code is here for your review.

@jeremystretch commented on GitHub (Oct 15, 2020): The relevant code is [here](https://github.com/netbox-community/netbox/blob/87c13a876b6a1975e79b8a12ca0ad8569a3e8aea/netbox/ipam/api/views.py#L171) for your review.
adam commented 2025-12-29 18:33:42 +01:00
Author
Owner
Copy Link

@tomasherout commented on GitHub (Oct 16, 2020):

After code inspection it's clear that API also accept array as input a then response is also array.

From Swagger point of view is not make sense - in case, when object is input, then object is result, not array.

I think could be correct change 87c13a876b/netbox/ipam/api/views.py (L168) to many=True (it's universal)

Otherwise, generated API clients does not work.

BTW: in GraphQL schema is not possible do things like this because it's really not good idea.

@tomasherout commented on GitHub (Oct 16, 2020): After code inspection it's clear that API also accept array as input a then response is also array. From Swagger point of view is not make sense - in case, when object is input, then object is result, not array. I think could be correct change https://github.com/netbox-community/netbox/blob/87c13a876b6a1975e79b8a12ca0ad8569a3e8aea/netbox/ipam/api/views.py#L168 to `many=True` (it's universal) Otherwise, generated API clients **does not work**. BTW: in GraphQL schema is not possible do things like this because it's really not good idea.
adam commented 2025-12-29 18:33:43 +01:00
Author
Owner
Copy Link

@jeremystretch commented on GitHub (Oct 16, 2020):

Otherwise, generated API clients does not work.

This is not a primary concern for us. My primary concern is how easy the REST API is for the user to consume. Supporting both single- and multi-object requests via the same endpoint is more convenient for the end user, so that's the approach we've taken.

@jeremystretch commented on GitHub (Oct 16, 2020): > Otherwise, generated API clients does not work. This is not a primary concern for us. My primary concern is how easy the REST API is for the user to consume. Supporting both single- and multi-object requests via the same endpoint is more convenient for the end user, so that's the approach we've taken.
adam commented 2025-12-29 18:33:43 +01:00
Author
Owner
Copy Link

@tomasherout commented on GitHub (Oct 16, 2020):

But fix is related to Swagger metadata only. There is no change for user and API capability to accept & return of object and arrays.

@tomasherout commented on GitHub (Oct 16, 2020): But fix is related to Swagger metadata only. There is no change for user and API capability to accept & return of object and arrays.
adam commented 2025-12-29 18:33:43 +01:00
Author
Owner
Copy Link

@jeremystretch commented on GitHub (Oct 20, 2020):

@tomasherout would you like to volunteer to own this issue?

@jeremystretch commented on GitHub (Oct 20, 2020): @tomasherout would you like to volunteer to own this issue?
adam commented 2025-12-29 18:33:43 +01:00
Author
Owner
Copy Link

@tomasherout commented on GitHub (Oct 21, 2020):

I can try it

@tomasherout commented on GitHub (Oct 21, 2020): I can try it
adam commented 2025-12-29 18:33:43 +01:00
Author
Owner
Copy Link

@tomasherout commented on GitHub (Oct 29, 2020):

I tried some ideas and I see two options:

  1. change many=True to many=False for response at: 87c13a876b/netbox/ipam/api/views.py (L167)

=> Swagger says method "accept one, returns one" and REST for input object returns object (not arrays). It's in match.

  1. change many=False to many=True for request at: 87c13a876b/netbox/ipam/api/views.py (L168)

Then modify method to way: when array was received, then return array (in case one IP was found). (EDIT: It's already there)

But, I have problem with this due to:

  File ".../netbox/venv/lib/python3.7/site-packages/drf_yasg/inspectors/view.py", line 71, in get_request_body_parameters
    serializer = self.get_request_serializer()
  File ".../netbox/netbox/utilities/custom_inspectors.py", line 20, in get_request_serializer
    for child_name, child in serializer.fields.items():
AttributeError: 'ListSerializer' object has no attribute 'fields'
[29/Oct/2020 17:51:33] "GET /api/docs/?format=openapi HTTP/1.1" 500 165705

I'm Django greenhorn so please give me some ideas how to fix it? Make different serializer? I was looking for similar case in code, but I was not able to find any place where many can be in request.

What is preferable solution? Option 1, 2 or different for you @jeremystretch ? Thanks a lot.

@tomasherout commented on GitHub (Oct 29, 2020): I tried some ideas and I see two options: 1) change `many=True` to `many=False` for response at: https://github.com/netbox-community/netbox/blob/87c13a876b6a1975e79b8a12ca0ad8569a3e8aea/netbox/ipam/api/views.py#L167 => Swagger says method "_accept one, returns one_" and REST for _input object returns object_ (not arrays). It's in match. 2) change `many=False` to `many=True` for request at: https://github.com/netbox-community/netbox/blob/87c13a876b6a1975e79b8a12ca0ad8569a3e8aea/netbox/ipam/api/views.py#L168 ~~Then modify method to way: _when array was received, then return array_ (in case one IP was found).~~ (EDIT: It's already there) But, I have problem with this due to: ``` File ".../netbox/venv/lib/python3.7/site-packages/drf_yasg/inspectors/view.py", line 71, in get_request_body_parameters serializer = self.get_request_serializer() File ".../netbox/netbox/utilities/custom_inspectors.py", line 20, in get_request_serializer for child_name, child in serializer.fields.items(): AttributeError: 'ListSerializer' object has no attribute 'fields' [29/Oct/2020 17:51:33] "GET /api/docs/?format=openapi HTTP/1.1" 500 165705 ``` I'm Django greenhorn so please give me some ideas how to fix it? Make different serializer? I was looking for similar case in code, but I was not able to find any place where `many` can be in request. What is preferable solution? Option 1, 2 or different for you @jeremystretch ? Thanks a lot.
adam commented 2025-12-29 18:33:43 +01:00
Author
Owner
Copy Link

@DanSheps commented on GitHub (Dec 16, 2020):

The Request and Response should be set to accept many IMO.

@DanSheps commented on GitHub (Dec 16, 2020): The Request and Response should be set to accept many IMO.
adam commented 2025-12-29 18:33:43 +01:00
Author
Owner
Copy Link

@jeremystretch commented on GitHub (Dec 17, 2020):

I agree with @DanSheps: It makes sense to just force many for both read and write.

@jeremystretch commented on GitHub (Dec 17, 2020): I agree with @DanSheps: It makes sense to just force many for both read and write.
adam commented 2025-12-29 18:33:44 +01:00
Author
Owner
Copy Link

@tomasherout commented on GitHub (Dec 18, 2020):

OK, I agree ... but, I need some help how to solve serializer issue:

  File ".../netbox/venv/lib/python3.7/site-packages/drf_yasg/inspectors/view.py", line 71, in get_request_body_parameters
    serializer = self.get_request_serializer()
  File ".../netbox/netbox/utilities/custom_inspectors.py", line 20, in get_request_serializer
    for child_name, child in serializer.fields.items():
AttributeError: 'ListSerializer' object has no attribute 'fields'
[29/Oct/2020 17:51:33] "GET /api/docs/?format=openapi HTTP/1.1" 500 165705

Thanks

@tomasherout commented on GitHub (Dec 18, 2020): OK, I agree ... but, I need some help how to solve serializer issue: ``` File ".../netbox/venv/lib/python3.7/site-packages/drf_yasg/inspectors/view.py", line 71, in get_request_body_parameters serializer = self.get_request_serializer() File ".../netbox/netbox/utilities/custom_inspectors.py", line 20, in get_request_serializer for child_name, child in serializer.fields.items(): AttributeError: 'ListSerializer' object has no attribute 'fields' [29/Oct/2020 17:51:33] "GET /api/docs/?format=openapi HTTP/1.1" 500 165705 ``` Thanks
adam commented 2025-12-29 18:33:44 +01:00
Author
Owner
Copy Link

@jeremystretch commented on GitHub (Jan 25, 2021):

Removing @tomasherout as it has been over a month with no updates.

@jeremystretch commented on GitHub (Jan 25, 2021): Removing @tomasherout as it has been over a month with no updates.
Sign in to join this conversation.
No Branch/Tag Specified
Branches Tags
Labels
Clear labels
beta
breaking change
complexity: high
complexity: low
complexity: medium
needs milestone
netbox
pending closure
plugin candidate
pull-request
Mirrored from GitHub Pull Request
 severity: high
severity: low
severity: medium
status: accepted
status: backlog
status: blocked
status: duplicate
status: needs owner
status: needs triage
status: revisions needed
status: under review
topic: GraphQL
topic: Internationalization
topic: OpenAPI
topic: UI/UX
topic: cabling
topic: event rules
topic: htmx navigation
topic: industrialization
topic: migrations
topic: plugins
topic: scripts
topic: templating
topic: testing
type: bug
type: deprecation
type: documentation
type: feature
type: housekeeping
type: translation
No Label status: accepted type: bug
Milestone
No items
No Milestone
Projects
Clear projects
No project
Assignees
Clear assignees
adam
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: starred/netbox#4185
Delete Branch "%!s()"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?