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

[PR #1930] [MERGED] Use drf_yasg to generate swagger #12287

New Issue
Closed
opened 2025-12-29 22:20:40 +01:00 by adam · 0 comments
adam commented 2025-12-29 22:20:40 +01:00
Owner
Copy Link

📋 Pull Request Information

Original PR: https://github.com/netbox-community/netbox/pull/1930
Author: @davcamer
Created: 2/28/2018
Status: ✅ Merged
Merged: 3/21/2018
Merged by: @jeremystretch

Base: develop ← Head: drf-yasg

📝 Commits (4)

  • b83de7e Use drf_yasg to generate swagger
  • 53e4e74 Differentiate better between boolean and 0, 1 choices
  • e071b7d The id__in field is a csv-separated string of ids
  • b5f1d74 Definition for /dcim/connected-device/ endpoint

📊 Changes

6 files changed (+133 additions, -7 deletions)

View changed files

📝 netbox/dcim/api/views.py (+11 -2)
📝 netbox/netbox/settings.py (+27 -1)
📝 netbox/netbox/urls.py (+17 -3)
➕ netbox/utilities/custom_inspectors.py (+76 -0)
📝 old_requirements.txt (+1 -0)
📝 requirements.txt (+1 -1)

📄 Description

Fixes:

#1853
#1855
https://github.com/digitalocean/go-netbox/issues/26

drf_yasg provides more complete swagger output, allowing for generation of usable clients. As explained in drf_yasg's README, the django rest framework is based on coreapi, which doesn't include response schemas. drf_yasg instead approaches the swagger with openapi, allowing it to generate full response schemas.

Some custom work was needed to accommodate Netbox's custom field serializers, and to provide x-nullable attributes where appropriate. x-nullable is an extension to OpenAPI v2, but is understood by the golang swagger generator I was targeting. I have not tried it with other generators.

This also replaces the api documentation at /api/docs with similar documentation, also based off of the swagger UI. There is alternative documentation at /api/redoc/ included only because it is by default part of drf_yasg. That could easily be removed if it isn't desired.

One other note: I was not able to get old_requirements.txt to work as expected with more than a single line in it. It simply errors out when the pycrypto is not installed, because of the previous upgrade.

$ pip3 --version
pip 9.0.1 from /usr/local/lib/python3.6/site-packages (python 3.6)
$ pip3 uninstall -r old_requirements.txt -y
Uninstalling psycopg2-2.7.4:
  Successfully uninstalled psycopg2-2.7.4
Cannot uninstall requirement pycrypto, not installed

Based on what you've done with psycopg2, I've moved django-rest-swagger to the top of that file.

🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.

## 📋 Pull Request Information **Original PR:** https://github.com/netbox-community/netbox/pull/1930 **Author:** [@davcamer](https://github.com/davcamer) **Created:** 2/28/2018 **Status:** ✅ Merged **Merged:** 3/21/2018 **Merged by:** [@jeremystretch](https://github.com/jeremystretch) **Base:** `develop` ← **Head:** `drf-yasg` --- ### 📝 Commits (4) - [`b83de7e`](https://github.com/netbox-community/netbox/commit/b83de7eb1183c68697fa7aa6f2179c40a4c1344e) Use drf_yasg to generate swagger - [`53e4e74`](https://github.com/netbox-community/netbox/commit/53e4e749307e98834786065fdc6ad844f8c9794c) Differentiate better between boolean and 0, 1 choices - [`e071b7d`](https://github.com/netbox-community/netbox/commit/e071b7dfd53ca74f2b1dda5f93682d146d79bd13) The id__in field is a csv-separated string of ids - [`b5f1d74`](https://github.com/netbox-community/netbox/commit/b5f1d74d6feb800b0bdd11ba95aaf1b9c82afcbe) Definition for /dcim/connected-device/ endpoint ### 📊 Changes **6 files changed** (+133 additions, -7 deletions) <details> <summary>View changed files</summary> 📝 `netbox/dcim/api/views.py` (+11 -2) 📝 `netbox/netbox/settings.py` (+27 -1) 📝 `netbox/netbox/urls.py` (+17 -3) ➕ `netbox/utilities/custom_inspectors.py` (+76 -0) 📝 `old_requirements.txt` (+1 -0) 📝 `requirements.txt` (+1 -1) </details> ### 📄 Description <!-- Thank you for your interest in contributing to NetBox! Please note that our contribution policy requires that a feature request or bug report be opened for approval prior to filing a pull request. This helps avoid wasting time and effort on something that we might not be able to accept. Please indicate the relevant feature request or bug report below. --> ### Fixes: #1853 #1855 https://github.com/digitalocean/go-netbox/issues/26 <!-- Please include a summary of the proposed changes below. --> drf_yasg provides more complete swagger output, allowing for generation of usable clients. As explained in [drf_yasg's README](https://github.com/axnsan12/drf-yasg/#swagger-in-django-rest-framework), the django rest framework is based on coreapi, which doesn't include response schemas. drf_yasg instead approaches the swagger with openapi, allowing it to generate full response schemas. Some custom work was needed to accommodate Netbox's custom field serializers, and to provide `x-nullable` attributes where appropriate. `x-nullable` is an [extension](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#specification-extensions) to OpenAPI v2, but is understood by the golang swagger generator I was targeting. I have not tried it with other generators. This also replaces the api documentation at `/api/docs` with similar documentation, also based off of the swagger UI. There is alternative documentation at `/api/redoc/` included only because it is by default part of drf_yasg. That could easily be removed if it isn't desired. One other note: I was not able to get `old_requirements.txt` to work as expected with more than a single line in it. It simply errors out when the `pycrypto` is not installed, because of the previous upgrade. ``` $ pip3 --version pip 9.0.1 from /usr/local/lib/python3.6/site-packages (python 3.6) $ pip3 uninstall -r old_requirements.txt -y Uninstalling psycopg2-2.7.4: Successfully uninstalled psycopg2-2.7.4 Cannot uninstall requirement pycrypto, not installed ``` Based on what you've done with psycopg2, I've moved django-rest-swagger to the top of that file. --- <sub>🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.</sub>
adam added the pull-request label 2025-12-29 22:20:40 +01:00
adam closed this issue 2025-12-29 22:20:40 +01:00
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 pull-request
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#12287
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?