Hacktoberfest 2026: the issues maintainers tagged for October, open and beginner-friendly. Browse Hacktoberfest issues

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

Open
#740 2 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Assessment

Difficulty
5/5
Estimated time
Over a week
Newbie friendliness
30/100
Issue type
Feature
Clarity
Mostly clear
Activity status
Stale
Tech stack
azure
Domain
api, devops

Research direction

Start with the API specification upload and extract pipeline flow described in the issue, including its generated artifacts and APIM publishing step. Review how service URLs, OAuth security protocols, examples, and added properties are represented across the extracted specification and APIM. Done would be a defined approach for modifying selected specification parts without wiping APIM settings or removing the API from the developer portal.

Written by the indexing model from the issue text.

Description

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.

Dominant language
C#
Stars
448
Forks
247
No merged PRs in 30d

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from Azure/apiops

All issues in Azure/apiops

Similar issues

More C# issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.