Giter Site home page Giter Site logo

azure-rest-api-specs's Introduction

Repo Status

Azure REST API Specifications

Code of Conduct

This project has adopted the Microsoft Open Source Code of Conduct. For more information see the Code of Conduct FAQ or contact [email protected] with any additional questions or comments.

Description

This repository is the canonical source for REST API specifications for Microsoft Azure.

Creating the Swagger Specification for Azure

  • This document will help you understand how AutoRest converts Swagger in to code.
  • If you are using swashbuckle to generate a swagger spec from your .NET WEB API then please take a look at this repo.
  • Swagger spec for every api-version should be in a serate folder named with the api-version.
    • It is time consuming to review the file line by line for every api-version. When you are creating the swagger spec for the new api-version, please copy the swagger spec from the previous version in to the new api-versioned folder and commit it. After that overwrite it with the changes for the new api-version. This makes it easy for us to review the changes.

Directory Structure

The structure of the directory should strictly follow these rules:

  • The top level folder must be the service name
  • The second level must be the API versions
  • The third level must be the format of the specification
  • The fourth level must be the specifications

The structure should appear like so:

.
├── arm-authorization
│   └── 2015-01-01
│       └── swagger
│           └── authorization.json
├── arm-compute
│   └── 2015-06-15
│       └── swagger
│           └── service.json
├── arm-features
│   └── 2014-08-01-preview
│       └── swagger
│           └── features.json
├── arm-network
│   └── 2015-05-01-preview
│       └── swagger
│           └── service.json
├── arm-resources
│   └── 2014-04-01-preview
│       └── swagger
│           └── service.json
├── arm-storage
│   └── 2015-05-01-preview
│       └── swagger
│           └── service.json
├── arm-subscriptions
│   └── 2014-04-01-preview
│       └── swagger
│           └── service.json
├── arm-web
├── documentation
└── readme.md

At this point, the specifications are expected to be in swagger format

How to validate your swagger

Generating Code from Specifications

If you are interested in generating code from these specifications, please check out AutoRest. There you will find the code generator as well as instructions on how to use it.

How to Contribute

Please contribute to services you know and love. The curation of these specifications will ensure that we have great documentation and even better client library support for our Azure Services. If you have any questions, please reach out to the autoresteng dl.

Submitting changes

Please send a GitHub Pull Request to Azure REST API Specs with a clear list of what you've done (read more about pull requests). When you send a pull request, we will love you forever if you include additions to the documentation for your given service. We can always use more documentation and beautiful markdown. Please follow make sure all of your commits are atomic (one feature per commit).

Always write a clear log message for your commits. One-line messages are fine for small changes, but bigger changes should look like this:

$ git commit -m "A brief summary of the commit
>
> A paragraph describing what changed and its impact."

Please be kind with your pull requests and ensure you keeping them as focused and cohesive as possible. Keep your pull request free of merge commits, code review fixes and anything that may take away from the essence of your contribution. Use the git tools you have available to you, such as amend, rebase, etc.

azure-rest-api-specs's People

Contributors

amarzavery avatar begoldsm avatar brjohnstmsft avatar deepakrajendranmsft avatar deepakswifty avatar devigned avatar dihan0604 avatar fearthecowboy avatar huangpf avatar hyonholee avatar jeffreychenmsft avatar jianghaolu avatar lmazuel avatar markcowl avatar matt1883 avatar matthchr avatar ms-alguerra avatar pankajsn avatar pinwang81 avatar sazeesha avatar stankovski avatar tbombach avatar tiano2017 avatar vinatara avatar vishrutshah avatar vivsriaus avatar vrmurthy01 avatar x10shun avatar xingwu1 avatar yaakoviyun avatar

Watchers

 avatar  avatar

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. 📊📈🎉

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google ❤️ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.