[Question] What is recommended practices for developers when making changes to our api specification

[MattHartz]

Release version

Not sure

Question Details

Creating a new API in APIM from an API spec (using swagger) is super easy with some caveats.

Go into API, upload openAPI spec, run extract pipeline, the artifacts here and there, and then commit and publish.

Where i'm struggling is making modifications. There are so many things that differ when running in APIM vs what is extracted from a swagger API spec makes this very difficult. For example, all my serviceUrls, OAuth security protocols, examples, etc get wiped or modified even adding a single property to an API is annoying.

We basically have to manually do everything, or optionally completely republish/extract but that removes API from developer portal during the process.

Expected behavior

Maybe break up api specification up in a way that might be easier to digest and only need to modify particular files. Maybe provide a openapi specification (extracted from service) and have overrides in other configuration files for securityschemas as an example.

Actual behavior

everything is contained in api specification

Reproduction Steps

I think i put enough detail above.

[github-actions[bot]]

  Thank you for opening this issue! Please be patient while we will look into it and get back to you as this is an open source project. In the meantime make sure you take a look at the [closed issues](https://github.com/Azure/apiops/issues?q=is%3Aissue+is%3Aclosed) in case your question has already been answered. Don't forget to provide any additional information if needed (e.g. scrubbed logs, detailed feature requests,etc.).
  Whenever it's feasible, please don't hesitate to send a Pull Request (PR) our way. We'd greatly appreciate it, and we'll gladly assess and incorporate your changes.

[shawnmurtagh]

Hey @MattHartz - we saw the same issue in development processes. We decided to choose between Design-First (Manually update OAS), Portal-First (extractor only), or Code-First (SwaggerUI). We chose design-first for Data APIs to give our BAs and Devs the chance to collab and then generate boilerplate based on a complete OAS. Experience APIs tend to use code-first.

These few block of pipeline code added to the extractor can prevent portal-first changes if you choose design-first which we found critical since APIM refactors your OAS to its own flavor.

parameters:
  - name: API_SPECIFICATION_IGNORE_PORTAL_UPDATES
  displayName: Ignore portal updates to OpenAPI Specification
  type: boolean
  default: true

# pipeline....

# just before commit
$ignorePortalSpecUpdates = "${{ parameters.API_SPECIFICATION_IGNORE_PORTAL_UPDATES }}"
    if ($ignorePortalSpecUpdates -eq $true) {
      Write-Information "Executing git reset on OpenAPI Specification files"
      git -C "$temporaryFolderPath" reset artifacts/apis/*/specification.json
      git -C "$temporaryFolderPath" reset artifacts/apis/*/specification.yaml
      if ($LASTEXITCODE -ne 0) { throw "git reset on OpenAPI Specification files failed." }
    }