Currently it is unclear how to get an environment set up to develop in. Taking the approach from the GitHub actions file doesn't work to bring up the environment, the oapi container fails to start.

❯ docker-compose --project-name go_nautobot -f development/docker-compose.yml up --build --abort-on-container-exit
Creating network "go_nautobot_default" with the default driver
Creating volume "go_nautobot_postgres_data" with default driver
Building oapi
[+] Building 0.9s (11/11) FINISHED                                                                                                                                                                                      
 => [internal] load build definition from Dockerfile                                                                                                                                                               0.0s
 => => transferring dockerfile: 303B                                                                                                                                                                               0.0s
 => [internal] load .dockerignore                                                                                                                                                                                  0.0s
 => => transferring context: 2B                                                                                                                                                                                    0.0s
 => [internal] load metadata for docker.io/library/golang:1.18-alpine                                                                                                                                              0.8s
 => [1/6] FROM docker.io/library/golang:1.18-alpine@sha256:8e45e2ef37d2b6d98900392029db2bc88f42c0f2a9a8035fa7da90014698e86b                                                                                        0.0s
 => [internal] load build context                                                                                                                                                                                  0.0s
 => => transferring context: 931B                                                                                                                                                                                  0.0s
 => CACHED [2/6] WORKDIR /app                                                                                                                                                                                      0.0s
 => CACHED [3/6] RUN apk update     && apk add gcc musl-dev gcompat                                                                                                                                                0.0s
 => CACHED [4/6] RUN go install github.com/deepmap/oapi-codegen/cmd/[email protected]                                                                                                                           0.0s
 => CACHED [5/6] COPY development/generate.sh ./                                                                                                                                                                   0.0s
 => CACHED [6/6] COPY development/oapi-config.yml ./                                                                                                                                                               0.0s
 => exporting to image                                                                                                                                                                                             0.0s
 => => exporting layers                                                                                                                                                                                            0.0s
 => => writing image sha256:ff18519cc3c23cef2a4896837db45f5c7b147a00d47d57a7a3ca69a882b0862c                                                                                                                       0.0s
 => => naming to docker.io/networktocode/oapi:local                                                                                                                                                                0.0s

Use 'docker scan' to run Snyk tests against images to find vulnerabilities and learn how to fix them
Creating go_nautobot_db_1    ... done
Creating go_nautobot_redis_1 ... done
Creating go_nautobot_nautobot_1 ... done
Creating go_nautobot_celery_worker_1 ... done

ERROR: for oapi  Container "8e97fc46adff" is unhealthy.
ERROR: Encountered errors while bringing up the project.

It should cover CRUD operations:

• Create object
• Read object
• Update object
• Delete object
• Create Bulk objects
• Update Bulk objects
• Delete Bulk objects

When nautobot/nautobot#2411 is in, we could get rid of the crafted patch.go

The team should be aware of a new release, or failure to troubleshoot

Think about enforcing the usage of explicit API versions to make sure that expectations always line up with reality.
See here:

• nautobot/nautobot#2799 (comment)
• nautobot/pynautobot#104

What's the plan for documenting the API of this SDK? Obviously there are patterns in the generated code, but does the user just have to do a search of nautobot.go to find the function they need, or is there some way that documentation can be provided?

The autogenerated file nautobot.go is not being indexed by default by some IDSs, such as Goland, due to its large file size. Additionally, there is currently no Godoc documentation generated for this package.

To address this issue, the code should probably be split into different files based on the autogenerated models/types, clients and multiple packages for the different api endpoint/tags defined in the swagger file.

This would reduce the filesize and also the size of the compiled binary when only some endpoints are used.

• Seems like there's room for some common helper functions, such as checking that error != nil (or failing the test) and checking that the response is a 2xx (or failing the test).
• Bulk operations test looks to be missing bulk-create and bulk-partial-update (PATCH) operations coverage
• Single operations test looks to be missing partial-update (PATCH) coverage
• Probably don't need to test CRUD for all models but it's worth thinking about testing the various bespoke endpoints (devices/napalm, jobs/run, prefixes/available-prefixes, etc.) to confirm that they appear to work correctly as generated.

After the Nautobot docker image is published, it should trigger this pipeline to auto-generate a new release

It would be good to regenerate development/nautobot_config.py with latest Nautobot version as I see a lot of configs being explicitly specified in this file that should normally be fine to leave as default - plus potentially problematic (if likely irrelevant to this particular project) legacy settings like CACHEOPS_ENABLED = True.

• Should the default nautobot_ver in tasks.py be updated every time there's a new Nautobot release?
• Actually, are any/all of the tasks in tasks.py even relevant to this project? Would be good to remove ones that don't apply.

Problem statement

If we follow the Nautobot versioning schema 1:1 then we cannot release fixed versions for a given Nautobot versions, that means if there is a problem with the oapi code generation in a given release the only thing we can do is delete the already released version, potentially breaking other peoples code. As far as I can see SemVer doesn't allow for any versioning in addition to major.minor.patch, build metadata has to be ignored for version precedence checking and we aren't dealing with pre-releases here.

Open points

• Research how similar libraries solve this issue
• Research whether the API spec even changes with patch releases, thereby maybe obviating the need for tightly coupled versioning

• Test cases look like a good start!
  • Seems like there's room for some common helper functions, such as checking that error != nil (or failing the test) and checking that the response is a 2xx (or failing the test).
  • Bulk operations test looks to be missing bulk-create and bulk-partial-update (PATCH) operations coverage
  • Single operations test looks to be missing partial-update (PATCH) coverage
  • Probably don't need to test CRUD for all models but it's worth thinking about testing the various bespoke endpoints (devices/napalm, jobs/run, prefixes/available-prefixes, etc.) to confirm that they appear to work correctly as generated.
• What's the plan for documenting the API of this SDK? Obviously there are patterns in the generated code, but does the user just have to do a search of nautobot.go to find the function they need, or is there some way that documentation can be provided?
• Should the default nautobot_ver in tasks.py be updated every time there's a new Nautobot release?
• What about the version in ci.yml?
• Actually, are any/all of the tasks in tasks.py even relevant to this project? Would be good to remove ones that don't apply.
• It would be good to regenerate development/nautobot_config.py with latest Nautobot version as I see a lot of configs being explicitly specified in this file that should normally be fine to leave as default - plus potentially problematic (if likely irrelevant to this particular project) legacy settings like CACHEOPS_ENABLED = True.

All in all, looks very promising!

The current README provides a good baseline. I'd like us to investigate some of the extras listed below within the context of how all other Nautobot project documentation is presented (via docs.nautobot.com).

Open questions:

• I assume the invoke part (python dependency) is required only for development? Since the project straddles two languages because of Nautobot, it's probably OK. But there is no guidance provided for its usage (consider a go dev coming here with no python knowledge).
• Have you considered building a docs site using mkdocs? Since we're using some python tooling that could be fine to augment the automatic godoc stuff that will be generated by google.

Working from the following checklist:

• Reviewed #21 with comments - CS
• Test Customization instructions from scratch - CS
• Test howto main example - CS
• Investigate hosting a docs site based on the nautobot standard docs
• Investigate godoc output (possibly markdown files we could host/integrate with mkdocs?)