diff --git a/.all-contributorsrc b/.all-contributorsrc index 272f96fe2..c1cb2a3a5 100644 --- a/.all-contributorsrc +++ b/.all-contributorsrc @@ -145,7 +145,9 @@ "profile": "https://waleedashraf.me/", "contributions": [ "talk", - "ideas" + "ideas", + "doc", + "example" ] }, { @@ -215,7 +217,12 @@ "profile": "https://github.com/magicmatatjahu", "contributions": [ "review", - "ideas" + "ideas", + "question", + "bug", + "doc", + "example", + "maintenance" ] }, { @@ -224,7 +231,11 @@ "avatar_url": "https://avatars.githubusercontent.com/u/193286?v=4", "profile": "https://vladimirgorej.com/", "contributions": [ - "doc" + "doc", + "bug", + "example", + "ideas", + "review" ] }, { @@ -271,7 +282,12 @@ "contributions": [ "review", "ideas", - "question" + "question", + "blog", + "bug", + "doc", + "example", + "maintenance" ] }, { @@ -320,6 +336,49 @@ "contributions": [ "doc" ] + }, + { + "login": "luphieanza", + "name": "Muhammad Rafly Andrianza", + "avatar_url": "https://avatars.githubusercontent.com/u/20577131?v=4", + "profile": "https://github.com/luphieanza", + "contributions": [ + "doc" + ] + }, + { + "login": "danielkocot", + "name": "Daniel Kocot", + "avatar_url": "https://avatars.githubusercontent.com/u/466609?v=4", + "profile": "https://danielkocot.github.io/", + "contributions": [ + "doc", + "example", + "ideas" + ] + }, + { + "login": "sekharbans-ebay", + "name": "sekharbans-ebay", + "avatar_url": "https://avatars.githubusercontent.com/u/66145510?v=4", + "profile": "https://github.com/sekharbans-ebay", + "contributions": [ + "doc", + "example", + "ideas" + ] + }, + { + "login": "damaru-inc", + "name": "Michael Davis", + "avatar_url": "https://avatars.githubusercontent.com/u/3926925?v=4", + "profile": "http://www.damaru.com/", + "contributions": [ + "bug", + "doc", + "example", + "ideas" + ] } ], "commitConvention": "none" diff --git a/.github/scripts/remove-toc.js b/.github/scripts/remove-toc.js index b1305b21b..29adb5882 100644 --- a/.github/scripts/remove-toc.js +++ b/.github/scripts/remove-toc.js @@ -9,7 +9,7 @@ module.exports = (givenSpec) => { const startingLine = "## Table of Contents\n"; const endingLine = "\n"; - const specFile = fs.readFileSync(`./website/pages/docs/specifications/${givenSpec}.md`); + const specFile = fs.readFileSync(`./website/pages/docs/reference/specification/${givenSpec}.md`); const startingIndex = specFile.indexOf(startingLine); const endingIndex = specFile.indexOf(endingLine); @@ -21,5 +21,5 @@ module.exports = (givenSpec) => { const firstHalf = specFile.slice(0, startingIndex); const secondHalf = specFile.slice(endingIndex + endingLine.length); const specWithoutToc = `${firstHalf}${secondHalf}`; - fs.writeFileSync(`./website/pages/docs/specifications/${givenSpec}.md`, specWithoutToc); + fs.writeFileSync(`./website/pages/docs/reference/specification/${givenSpec}.md`, specWithoutToc); } diff --git a/.github/workflows/add-good-first-issue-labels.yml b/.github/workflows/add-good-first-issue-labels.yml index 00acdb847..dee10e726 100644 --- a/.github/workflows/add-good-first-issue-labels.yml +++ b/.github/workflows/add-good-first-issue-labels.yml @@ -21,7 +21,7 @@ jobs: github-token: ${{ secrets.GH_TOKEN }} script: | const areas = ['javascript', 'typescript', 'java' , 'go', 'docs', 'ci-cd', 'design']; - const values = context.payload.comment.body.split(" "); + const values = context.payload.comment.body.trim().split(" "); switch(values[1]){ case 'ts': values[1] = 'typescript'; diff --git a/.github/workflows/automerge-for-humans-add-ready-to-merge-or-do-not-merge-label.yml b/.github/workflows/automerge-for-humans-add-ready-to-merge-or-do-not-merge-label.yml index c694c38fd..e00a45fa3 100644 --- a/.github/workflows/automerge-for-humans-add-ready-to-merge-or-do-not-merge-label.yml +++ b/.github/workflows/automerge-for-humans-add-ready-to-merge-or-do-not-merge-label.yml @@ -50,7 +50,7 @@ jobs: repo: pull.head.repo.name, basehead: `${pull.base.label}...${pull.head.label}`, }); - if (comparison.behind_by !== 0) { + if (comparison.behind_by !== 0 && pull.mergeable_state === 'behind') { console.log(`This branch is behind the target by ${comparison.behind_by} commits`) console.log('adding out-of-date comment...'); github.rest.issues.createComment({ @@ -108,4 +108,4 @@ jobs: owner: context.repo.owner, repo: context.repo.repo, labels: ['autoupdate'] - }) \ No newline at end of file + }) diff --git a/.github/workflows/automerge-orphans.yml b/.github/workflows/automerge-orphans.yml index 5c39ba921..20322ecb7 100644 --- a/.github/workflows/automerge-orphans.yml +++ b/.github/workflows/automerge-orphans.yml @@ -9,6 +9,7 @@ on: jobs: identify-orphans: + if: startsWith(github.repository, 'asyncapi/') name: Find orphans and notify runs-on: ubuntu-latest steps: @@ -57,7 +58,7 @@ jobs: name: Send info about orphan to slack uses: rtCamp/action-slack-notify@v2 env: - SLACK_WEBHOOK: ${{secrets.SLACK_GITHUB_NEWISSUEPR}} + SLACK_WEBHOOK: ${{secrets.SLACK_CI_FAIL_NOTIFY}} SLACK_TITLE: 🚨 Not merged PR that should be automerged 🚨 SLACK_MESSAGE: ${{steps.issuemarkdown.outputs.text}} MSG_MINIMAL: true \ No newline at end of file diff --git a/.github/workflows/autoupdate.yml b/.github/workflows/autoupdate.yml index f23ec3b88..ad8e0198f 100644 --- a/.github/workflows/autoupdate.yml +++ b/.github/workflows/autoupdate.yml @@ -20,13 +20,14 @@ on: jobs: autoupdate-for-bot: + if: startsWith(github.repository, 'asyncapi/') name: Autoupdate autoapproved PR created in the upstream runs-on: ubuntu-latest steps: - name: Autoupdating uses: docker://chinthakagodawita/autoupdate-action:v1 env: - GITHUB_TOKEN: '${{ secrets.GH_TOKEN }}' + GITHUB_TOKEN: '${{ secrets.GH_TOKEN_BOT_EVE }}' PR_FILTER: "labelled" PR_LABELS: "autoupdate" PR_READY_STATE: "ready_for_review" diff --git a/.github/workflows/help-command.yml b/.github/workflows/help-command.yml index 69163816e..03f891eba 100644 --- a/.github/workflows/help-command.yml +++ b/.github/workflows/help-command.yml @@ -25,7 +25,7 @@ jobs: - `/ready-to-merge` or `/rtm` - This comment will trigger automerge of PR in case all required checks are green, approvals in place and do-not-merge label is not added - `/do-not-merge` or `/dnm` - This comment will block automerging even if all conditions are met and ready-to-merge label is added - - `/autoupdate` or `/au` - This comment will add `autoupdate` label to the PR and keeps your PR up-to-date to the target branch's future changes. Unless there is a merge conflict. + - `/autoupdate` or `/au` - This comment will add `autoupdate` label to the PR and keeps your PR up-to-date to the target branch's future changes. Unless there is a merge conflict or it is a draft PR. create_help_comment_issue: if: ${{ !github.event.issue.pull_request && contains(github.event.comment.body, '/help') && github.actor != 'asyncapi-bot' }} runs-on: ubuntu-latest diff --git a/.github/workflows/link-check-cron.yml b/.github/workflows/link-check-cron.yml index 854c972e0..44e1a5cb0 100644 --- a/.github/workflows/link-check-cron.yml +++ b/.github/workflows/link-check-cron.yml @@ -11,13 +11,14 @@ on: jobs: External-link-validation-weekly: + if: startsWith(github.repository, 'asyncapi/') runs-on: ubuntu-latest steps: - uses: actions/checkout@v3 # Checks the status of hyperlinks in .md files - name: Check links - uses: derberg/github-action-markdown-link-check@temporary-fix + uses: gaurav-nelson/github-action-markdown-link-check@v1 with: use-quiet-mode: 'yes' use-verbose-mode: 'yes' @@ -32,5 +33,5 @@ jobs: status: ${{ job.status }} fields: repo,action,workflow env: - SLACK_WEBHOOK_URL: ${{ secrets.SLACK_DOCS_CHANNEL }} + SLACK_WEBHOOK_URL: ${{ secrets.SLACK_CI_FAIL_NOTIFY }} if: failure() # Only, on failure, send a message on the Slack Docs Channel (if there are broken links) diff --git a/.github/workflows/link-check-pr.yml b/.github/workflows/link-check-pr.yml index 4bdbad229..ecdf2b39b 100644 --- a/.github/workflows/link-check-pr.yml +++ b/.github/workflows/link-check-pr.yml @@ -16,7 +16,7 @@ jobs: - name: Checkout repo uses: actions/checkout@v3 - name: Check links - uses: derberg/github-action-markdown-link-check@temporary-fix + uses: gaurav-nelson/github-action-markdown-link-check@v1 with: use-quiet-mode: 'yes' use-verbose-mode: 'yes' diff --git a/.github/workflows/new-spec-release.yml b/.github/workflows/new-spec-release.yml index 8eef2276e..eadf1fda3 100644 --- a/.github/workflows/new-spec-release.yml +++ b/.github/workflows/new-spec-release.yml @@ -38,20 +38,20 @@ jobs: script: | const fs = require("fs"); - const specFiles = fs.readdirSync("./website/pages/docs/specifications"); + const specFiles = fs.readdirSync("./website/pages/docs/reference/specification"); const nextRelease = `${{github.event.release.tag_name}}`; const prefixRelease = nextRelease.split("-")[0]; for (const filename of specFiles) { if (filename.startsWith(prefixRelease)) { - fs.unlinkSync(`./website/pages/docs/specifications/${filename}`); + fs.unlinkSync(`./website/pages/docs/reference/specification/${filename}`); } } - name: Copy Spec file from Current Repo to Another working-directory: ./website run: | - cp ../spec/spec/asyncapi.md ./pages/docs/specifications/${{github.event.release.tag_name}}.md + cp ../spec/spec/asyncapi.md ./pages/docs/reference/specification/${{github.event.release.tag_name}}.md - name: Remove Table of Contents from Spec uses: actions/github-script@v4 with: @@ -71,7 +71,7 @@ jobs: const endingLine = "# LATEST-SPEC-REDIRECTION:END"; const releaseVersion = `${{github.event.release.tag_name}}`; - const redirectLine = `/docs/specifications/latest /docs/specifications/${releaseVersion} 302!\n`; + const redirectLine = `/docs/reference/specification/latest /docs/reference/specification/${releaseVersion} 302!\n`; const redirectFile = fs.readFileSync("./website/public/_redirects", "utf-8"); @@ -139,7 +139,7 @@ jobs: const releaseVersionWithoutV = releaseVersion.slice(1); - const redirectLine = `/docs/specifications/${releaseVersionWithoutV} /docs/specifications/${releaseVersion} 302!\n`; + const redirectLine = `/docs/reference/specification/${releaseVersionWithoutV} /docs/reference/specification/${releaseVersion} 302!\n`; const redirectFile = fs.readFileSync("./website/public/_redirects", "utf-8"); diff --git a/.github/workflows/stale-issues-prs.yml b/.github/workflows/stale-issues-prs.yml index 766731834..c1c0c61da 100644 --- a/.github/workflows/stale-issues-prs.yml +++ b/.github/workflows/stale-issues-prs.yml @@ -9,6 +9,7 @@ on: jobs: stale: + if: startsWith(github.repository, 'asyncapi/') name: Mark issue or PR as stale runs-on: ubuntu-latest steps: diff --git a/.github/workflows/update-spec.yaml b/.github/workflows/update-spec.yaml index 0dfa85ed1..528a66e5c 100644 --- a/.github/workflows/update-spec.yaml +++ b/.github/workflows/update-spec.yaml @@ -41,7 +41,7 @@ jobs: - name: Copy Spec file from Current Repo to Another working-directory: ./website run: | - cp ../spec/spec/asyncapi.md ./pages/docs/specifications/${{ steps.latest_version.outputs.latest_tag }}.md + cp ../spec/spec/asyncapi.md ./pages/docs/reference/specification/${{ steps.latest_version.outputs.latest_tag }}.md - name: Remove Table of Contents from Spec uses: actions/github-script@v4 with: diff --git a/.releaserc b/.releaserc index 80428b1af..fa26f7f73 100644 --- a/.releaserc +++ b/.releaserc @@ -1,7 +1,9 @@ --- branches: - master -- name: 2022-04-release +- name: next-spec + prerelease: true +- name: next-major-spec prerelease: true plugins: - - "@semantic-release/commit-analyzer" diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md new file mode 100644 index 000000000..638f73340 --- /dev/null +++ b/CODE_OF_CONDUCT.md @@ -0,0 +1,46 @@ +# Contributor Covenant Code of Conduct + +## Our Pledge + +In the interest of fostering an open and welcoming environment, we as contributors and maintainers pledge to make participation in our project and our community a harassment-free experience for everyone, regardless of age, body size, disability, ethnicity, gender identity and expression, level of experience, nationality, personal appearance, race, religion, or sexual identity and orientation. + +## Our Standards + +Examples of behavior that contributes to creating a positive environment include: + +- Using welcoming and inclusive language +- Being respectful of differing viewpoints and experiences +- Gracefully accepting constructive criticism +- Focusing on what is best for the community +- Showing empathy towards other community members + +Examples of unacceptable behavior by participants include: + +- The use of sexualized language or imagery and unwelcome sexual attention or advances +- Trolling, insulting/derogatory comments, and personal or political attacks +- Public or private harassment +- Publishing others' private information, such as a physical or electronic address, without explicit permission +- Other conduct which could reasonably be considered inappropriate in a professional setting + +## Our Responsibilities + +Project maintainers are responsible for clarifying the standards of acceptable behavior and are expected to take appropriate and fair corrective action in response to any instances of unacceptable behavior. + +Project maintainers have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct, or to ban temporarily or permanently any contributor for other behaviors that they deem inappropriate, threatening, offensive, or harmful. + +## Scope + +This Code of Conduct applies both within project spaces and in public spaces when an individual is representing the project or its community. Examples of representing a project or community include using an official project e-mail address, posting via an official social media account, or acting as an appointed representative at an online or offline event. Representation of a project may be further defined and clarified by project maintainers. + +## Enforcement + +Instances of abusive, harassing, or otherwise unacceptable behavior may be reported by contacting the project team at fmvilas@gmail.com. The project team will review and investigate all complaints, and will respond in a way that it deems appropriate to the circumstances. The project team is obligated to maintain confidentiality with regard to the reporter of an incident. Further details of specific enforcement policies may be posted separately. + +Project maintainers who do not follow or enforce the Code of Conduct in good faith may face temporary or permanent repercussions as determined by other members of the project's leadership. + +## Attribution + +This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4, available at [http://contributor-covenant.org/version/1/4][version] + +[homepage]: http://contributor-covenant.org +[version]: http://contributor-covenant.org/version/1/4/ diff --git a/README.md b/README.md index 4247448f3..6f100d2a3 100644 --- a/README.md +++ b/README.md @@ -41,6 +41,7 @@ The latest draft specification can be found at [spec/asyncapi.md](./spec/asyncapi.md) which tracks the latest commit to the master branch in this repository. - [Version 3.0.0](https://github.com/asyncapi/spec/blob/v3.0.0/spec/asyncapi.md) (latest) +- [Version 2.4.0](https://github.com/asyncapi/spec/blob/v2.4.0/spec/asyncapi.md) (latest) - [Version 2.3.0](https://github.com/asyncapi/spec/blob/v2.3.0/spec/asyncapi.md) - [Version 2.2.0](https://github.com/asyncapi/spec/blob/v2.2.0/spec/asyncapi.md) - [Version 2.1.0](https://github.com/asyncapi/spec/blob/v2.1.0/spec/asyncapi.md) @@ -104,26 +105,32 @@ Thanks goes to these wonderful people ([emoji key](https://allcontributors.org/d
Jonas Lagoni
🐛 📖 🤔 💬 👀 💡 -
Waleed Ashraf
📢 🤔 +
Waleed Ashraf
📢 🤔 📖 💡
Andrzej Jarzyna
📢
Emmelyn Wang
📝 🤔 📖 📢
Marc DiPasquale
📝 📢 👀 🐛 🤔 📹
Gerald Loeffler
📖 🐛 🤔
Dale Lane
📝 🤔 📹 📢 ✅ 📖 -
Maciej Urbańczyk
👀 🤔 -
Vladimir Gorej
📖 +
Maciej Urbańczyk
👀 🤔 💬 🐛 📖 💡 🚧 +
Vladimir Gorej
📖 🐛 💡 🤔 👀
Lorna Jane Mitchell
📢 🤔
Laurent Broudoux
📖 📝 📢 💡 🤔 👀
Jesse Menning
📝 📢 👀 🤔 -
Sergio Moya
👀 🤔 💬 +
Sergio Moya
👀 🤔 💬 📝 🐛 📖 💡 🚧
Alexander Balogh
📖 🐛
Khuda Dad Nomani
💡 🐛
Aaron Korver
📖
Orlov Valentine
📖
Moez Bouhlel
📖 + +
Muhammad Rafly Andrianza
📖 +
Daniel Kocot
📖 💡 🤔 +
sekharbans-ebay
📖 💡 🤔 +
Michael Davis
🐛 📖 💡 🤔 + diff --git a/RELEASE_PROCESS.md b/RELEASE_PROCESS.md index 07547270c..979e4a10f 100644 --- a/RELEASE_PROCESS.md +++ b/RELEASE_PROCESS.md @@ -84,33 +84,29 @@ A [template for a new release issue](https://github.com/asyncapi/spec/blob/maste An example is the [release issue for the 2.3.0](https://github.com/asyncapi/spec/issues/675) release. -### Step 3 - create release branches +### Step 3 - update release branches -Release branches must have a year and a month of the release as prefix: {YEAR_OF_RELEASE}-{MONTH_OF_RELEASE}-release. +Release branches should be present in the following repositories: -For example, a release created in September 2021 has a `2021-09-release` release branch. - -This image shows part of the GitHub UI that shows how you can create a new branch using default branch as a base. - -At the beginning of the release cycle, we need to have a new release branch created in the following repositories: - [spec](https://github.com/asyncapi/spec) where contributor works with the specification file, - [spec-json-schemas](https://github.com/asyncapi/spec-json-schemas) where contributor pushes changes to JSON Schema of the spec, - [parser-js](https://github.com/asyncapi/parser-js) where contributor makes necessary changes in the JavaScript Parser. + +Depending on the type of release you are working on, you should use one branch or another: -The [release coordinator](#%22release-coordinator%22) should decide what the branch name needs to be, and contact the [code owners](#code-owners) for each repository to ask them to create the branches for them. - - -### Step 4 - update release branches +- `next-spec`: for releasing minor versions. For example, `2.3.0` to `2.4.0`. +- `next-major-spec`: for releasing major versions. For example, `2.4.0` to `3.0.0`. -Once [release branches are created](#step-3---create-release-branches), there are some initial changes that need to be made. +Once you know which branch you should use, there are some initial changes that need to be made. The process for doing this is the same for each of these: -- the [release coordinator](#%22release-coordinator%22) should create a fork of the relevant repository for these changes +- the [release coordinator](#%22release-coordinator%22) should create a fork, if not created yet, of the relevant repository for these changes. +- the [release coordinator](#%22release-coordinator%22) should ensure the chosen **release branch** is up-to-date with the **default branch** (normally `master`) before adding any changes. - the commit message for the change should start with `chore:` -- the change should be contributed in a pull request targeting the [release branch](#step-3---create-release-branches) +- the change should be contributed in a pull request targeting the chosen **release branch**. - the [release coordinator](#%22release-coordinator%22) will need to ask the [code owners](#code-owners) for the relevant repository to approve and merge this pull request -#### Step 4.1 - Update version numbers in official examples +#### Step 3.1 - Update version numbers in official examples Repository: [spec](https://github.com/asyncapi/spec) Examples are located in the `examples/` folder in the [spec](https://github.com/asyncapi/spec) repository. They should all be updated to the new version number. @@ -119,7 +115,7 @@ An example of doing this is: - this [commit from the 2.3.0 release](https://github.com/dalelane/spec/commit/8c521539cd875470ea8e89cf3ab7ffd81be64788) - this [pull request from the 2.3.0 release](https://github.com/asyncapi/spec/pull/676) -#### Step 4.2 - Update version number in the spec +#### Step 3.2 - Update version number in the spec Repository: [spec](https://github.com/asyncapi/spec) References to the latest version in `spec/asyncapi.md` should be updated to the new version number. @@ -128,13 +124,13 @@ Examples of doing this are: - this [commit from the 2.3.0 release](https://github.com/asyncapi/spec/commit/1f29d803ca801756d4ea3f676bcf7e7751478de6) - this [commit from the 2.3.0 release](https://github.com/asyncapi/spec/commit/7f827a880fa3ddcbc9a39d50e41502bc450443bc) -#### Step 4.3 - Add new reference to the latest spec version in README +#### Step 3.3 - Add new reference to the latest spec version in README The new release should be listed in the [README.md](README.md) file and marked as `(latest)`. An example of doing this is: - this [commit from the 2.3.0 release](https://github.com/asyncapi/spec/pull/710/commits/22ba6c433ddbeeeda38f5aed55708826da62cf70) -#### Step 4.4 - Create a new JSON schema file for the new version +#### Step 3.4 - Create a new JSON schema file for the new version Repository: [spec-json-schemas](https://github.com/asyncapi/spec-json-schemas) The new file should be created in the `schemas/` folder in the [spec-json-schemas](https://github.com/asyncapi/spec-json-schemas) repository. @@ -145,7 +141,7 @@ An example of doing this is: - this [commit from the 2.3.0 release](https://github.com/dalelane/spec-json-schemas/commit/9cff7798ac42f609927e1cb9e532ff16d360ab99) - this [pull request from the 2.3.0 release](https://github.com/asyncapi/spec-json-schemas/pull/139) -#### Step 4.5 - Update the list of AsyncAPI schema MIME types with the new version +#### Step 3.5 - Update the list of AsyncAPI schema MIME types with the new version Repository: [parser-js](https://github.com/asyncapi/parser-js) The file to be updated is `lib/asyncapiSchemaFormatParser.js` in the [parser-js](https://github.com/asyncapi/parser-js) repository. @@ -156,35 +152,7 @@ An example of doing this is: - this [pull request from the 2.3.0 release](https://github.com/asyncapi/parser-js/pull/426) -### Step 5 - update default branches - -Once [release branches have been updated](#step-4---update-release-branches), the default (e.g. "master") branches should be updated to identify the new release branch. - -The process for doing this is the same for each of these: -- the [release coordinator](#%22release-coordinator%22) should create a fork of the relevant repository for these changes (_this can be the same fork as used for updating the release branches_) -- the commit message for the change should start with `chore:` -- the change should be contributed in a pull request targeting the **default branch** (normally `master`) -- the [release coordinator](#%22release-coordinator%22) will need to ask the [code owners](#code-owners) for the relevant repository to approve and merge this pull request - -#### Update package.json files -There are **two** repositories where `package.json` files need to be updated. In both repositories, the release branch name needs to be updated in the list of branches under `.release.branches`. - -- [parser-js](https://github.com/asyncapi/parser-js/blob/master/package.json#L90-L93) -- [spec-json-schemas](https://github.com/asyncapi/spec-json-schemas/blob/master/package.json#L48-L51) - -Examples of doing this are: -- this [commit from the 2.3.0 release for parser-js](https://github.com/dalelane/parser-js/commit/1d9f9ed52718269ffbce4d32bd4635c690371f80) -- this [commit from the 2.3.0 release for spec-json-schemas](https://github.com/dalelane/spec-json-schemas/commit/8a4b94aaf86240a6ca2aeb7ce3cc515bad283a2d) - - -#### Update .releaserc file -The release branch name needs to be updated in the `.releaserc` file in the [spec](https://github.com/asyncapi/spec) repository needs. - -An example of doing this is: -- this [commit from the 2.3.0 release](https://github.com/dalelane/spec/commit/210f89adc74f17aaf09d808b84132f232ff2e412) - - -### Step 6 - prepare announcement blog post +### Step 4 - prepare announcement blog post Each new release is announced by a blog post. You can see all of these at https://www.asyncapi.com/blog?tags=Release+Notes @@ -194,7 +162,7 @@ The steps to follow for this are: - Create a fork of the [website](https://github.com/asyncapi/website) repository - Create a new file at `pages/blog/release-notes-X.X.X.md` (replacing `X.X.X` with the version number for the release) - Add a standard header at the top of the file (see the release notes for [2.2.0](https://raw.githubusercontent.com/asyncapi/website/master/pages/blog/release-notes-2.2.0.md) and [2.3.0](https://raw.githubusercontent.com/asyncapi/website/master/pages/blog/release-notes-2.3.0.md) for examples) -- Add a (webp format) cover image to the `public/img/posts/release-notes-X.X.X/` folder, and update the `cover` attribute of the blog post header with it. (**Make sure to attribute the image correctly** - unsplash.com is a good source of free images for this). See [this commit from the 2.3.0 release](4050ca0540684f5188300e0c27efc713a6ba1ec2) for an example of doing this. +- Add a (webp format) cover image to the `public/img/posts/release-notes-X.X.X/` folder, and update the `cover` attribute of the blog post header with it. (**Make sure to attribute the image correctly** - unsplash.com is a good source of free images for this). See [this commit from the 2.3.0 release](https://github.com/asyncapi/website/pull/512/commits/4050ca0540684f5188300e0c27efc713a6ba1ec2) for an example of doing this. - Add a (webp format) profile picture of the release coordinator to the `public/img/avatars` folder, and update the `authors` attribute of the blog post header with it. See [this commit from the 2.3.0 release](https://github.com/asyncapi/website/pull/512/commits/006f7df26b0d0803ed2e1dd6b8004dfdaec15617) for an example of doing this. - Open a **draft** pull request against the [website](https://github.com/asyncapi/website/) repository. Make sure the option **Allow edits and access to secrets by maintainers** is selected to enable support from maintainers. This image shows example pull request created in GitHub with release notes for AsyncAPI specification @@ -203,7 +171,7 @@ An example of doing this is: - this [pull request from the 2.3.0 release](https://github.com/asyncapi/website/pull/512) -### Step 7 - create pull requests +### Step 5 - create pull requests Pull requests should be opened for all [repositories covered by this process](#repositories). @@ -217,7 +185,7 @@ Add a **autoupdate** label to the pull request by making a comment in the PR say _Note: The automation bot will keep the release branch up to date with the latest commits from the master branch (so long as there are no conflicts)._ -### Step 8 - bring updates into release branch +### Step 6 - bring updates into release branch The [release coordinator](#%22release-coordinator%22) should help to seek out possible updates that are good candidates for including in the release. @@ -235,7 +203,7 @@ Pull requests must be: - created in all repositories specified in contribution guide -### Step 9 - update announcement blog post +### Step 7 - update announcement blog post As features are identified for inclusion in the release, the [draft announcement blog post](#step-6---prepare-announcement-blog-post) should be updated with descriptions of them. The [release cooordinator](#%22release-coordinator%22) should coordinate with the feature contributors to write a description of each change. They should be able to provide input and also be allowed to work as co-authors for the release notes post. @@ -244,7 +212,7 @@ Changes in the specification need to be well described. We need clear informatio Every feature added to the [release branch](#step-3---create-release-branches) needs to be properly described in the release notes post. -### Step 10 - prepare release notes +### Step 8 - prepare release notes In addition to the [announcement blog post](#step-9---update-announcement-blog-post), the [release coordinator](#%22release-coordinator%22) should prepare release notes for each of the [repositories covered by this process](#repositories). @@ -258,7 +226,7 @@ Examples of doing this are: - the [release notes for version 2.3.0 of spec](https://github.com/asyncapi/spec/releases/tag/v2.3.0) -### Step 11 - notify people the release is coming +### Step 9 - notify people the release is coming As the release gets closer to being ready, it is helpful to remind the community that the release is on the way. @@ -271,12 +239,12 @@ This can also be done: Including a link to the [release issue](#step-2---create-a-release-issue) is a good way to let the community see the progress that has been made so far. -### Step 12 - reviews +### Step 10 - reviews At least one [code owner](#code-owners) must approve the [release pull requests](#step-7---create-pull-requests) in all related [repositories](#repositories). -### Step 13 - release candidates +### Step 11 - release candidates Pre-release release candidates are generated automatically by the automation bot when: - a pull request with a **fix** or **feat** prefix in the title is merged into the [release branch](#step-3---create-release-branches) @@ -290,11 +258,19 @@ Release candidates will include: An example release candidate is: https://github.com/asyncapi/spec/releases/tag/v2.3.0-2022-01-release.3 - **Important:** When release candidates are created for the [spec](https://github.com/asyncapi/spec) repository, the [parser-js](https://github.com/asyncapi/parser-js) repository will need to be updated to use that release candidate. +### Step 12 - Notify code owners of critical repositories about the pre-releases + +In order to let code owners of critical repositories have enough time to work on the changes needed on tooling, the [release coordinator](#%22release-coordinator%22) should notify code owners about the pre-releases. +As per today, the following repositories are considered critical: -### Step 14 - merge the release branches +- [HTML Template](https://github.com/asyncapi/html-template) +- [JavaScript Converter](https://github.com/asyncapi/converter-js/) +- [React component](https://github.com/asyncapi/asyncapi-react/) +- [Studio](https://github.com/asyncapi/studio) + +### Step 13 - merge the release branches Once everything is ready, it is time to merge the [release branches](#step-3---create-release-branches) using the [draft pull requests prepared earlier](#step-7---create-pull-requests). @@ -309,23 +285,52 @@ First, changes are merged into the `spec` repository, then `spec-json-schemas` a Release means merge of pull requests created from a release branch against the master branch. First, changes are merged into the `spec` repository, then `spec-json-schemas` and at the end in `parser-js`. Like in the case of the merge of release candidates, a pull request in `parser-js` can be merged only if it uses the final release of the new `@asyncapi/specs` package. -### Step 15 - publish releases +### Step 14 - publish releases The [release coordinator](#%22release-coordinator%22) should ask the [code owners](#code-owners) for each repository to update the release in Github created by the automation bot, by adding the [release notes they have prepared](#step-10---prepare-release-notes). -### Step 16 - notify tool maintainers +### Step 15 - notify tool maintainers + +Our current CI/CD automation will fill PR's updating the dependencies **automatically** on all repositories after the release. +However, the [release coordinator](#%22release-coordinator%22) should notify maintainers of the dependant repositories that a new release happened, as those might want to adopt the new features. -The [release coordinator](#%22release-coordinator%22) should notify maintainers of the following repositories that the first feature is merged and that release will be produced and therefore they need to start preparing for it: +Some of the dependant repositories are: + - [Avro Schema parser](https://github.com/asyncapi/avro-schema-parser) + - [Bundler](https://github.com/asyncapi/bundler) + - [CLI](https://github.com/asyncapi/cli) + - [Cupid](https://github.com/asyncapi/cupid) + - [Dot Net NATS template](https://github.com/asyncapi/dotnet-nats-template) + - [Generator](https://github.com/asyncapi/generator) + - [Generator React SDK](https://github.com/asyncapi/generator-react-sdk) + - [Glee](https://github.com/asyncapi/glee) + - [HTML Template](https://github.com/asyncapi/html-template) + - [Java Template](https://github.com/asyncapi/java-template) - [JavaScript Converter](https://github.com/asyncapi/converter-js/) - - [Playground](https://github.com/asyncapi/playground/) - - [React component](https://github.com/asyncapi/asyncapi-react/) - [Markdown template](https://github.com/asyncapi/markdown-template) + - [Modelina](https://github.com/asyncapi/modelina) + - [NodeJS WS Template](https://github.com/asyncapi/nodejs-ws-template) + - [Optimizer](https://github.com/asyncapi/optimizer) + - [Parser Go](https://github.com/asyncapi/parser-go) + - [React component](https://github.com/asyncapi/asyncapi-react/) + - [Server API](https://github.com/asyncapi/server-api/) + - [Simulator](https://github.com/asyncapi/simulator) + - [Studio](https://github.com/asyncapi/studio) + - [TS NATS Template](https://github.com/asyncapi/ts-nats-template) + +You can use Github Code Search to find the [list of repositories depending on parser-js or the specs](https://cs.github.com/?scopeName=All+repos&scope=&q=org%3Aasyncapi+%28path%3Apackage.json+OR+go.mod%29+%22%40asyncapi%2Fparser%22+OR+%22%40asyncapi%2Fspecs%22+OR+%22github.com%2Fasyncapi%2Fspec-json-schemas%22+OR+%22github.com%2Fasyncapi%2Fparser-go%22#). +Alternatively, you can use the following GH search queries: +- [NodeJS @asyncapi/specs dependants](https://github.com/search?q=org%3Aasyncapi+in%3Afile+filename%3Apackage.json+%22%40asyncapi%2Fspecs%22) +- [NodeJS @asyncapi/parser dependants](https://github.com/search?q=org%3Aasyncapi+in%3Afile+filename%3Apackage.json+%22%40asyncapi%2Fparser%22) +- [Go github.com/asyncapi/spec-json-schemas dependants](https://github.com/search?q=org%3Aasyncapi+in%3Afile+filename%3Ago.mod+%22%40github.com%2Fasyncapi%2Fspec-json-schemas%22) +- [Go github.com/asyncapi/parser-go dependants](https://github.com/search?q=org%3Aasyncapi+in%3Afile+filename%3Ago.mod+%22%40github.com%2Fasyncapi%2Fparser-go%22) + +You can check the following [example of notification to maintainers](https://github.com/asyncapi/spec/issues/735#issuecomment-1109801674). The [release coordinator](#%22release-coordinator%22) should also make sure other maintainers from other projects under the AsyncAPI GitHub organization released their packages. -### Step 17 - notify the community +### Step 16 - notify the community Every release of the release candidate is automatically published on the AsyncAPI Twitter account and in the releases-dedicated Slack channel. @@ -334,7 +339,7 @@ If the [release coordinator](#%22release-coordinator%22) uses social networks li Feel free to use other communication channels. Make sure that as many people as possible know about the change. Feel free to contact vendors upfront or other people that are interested in changes in the specification. -### Step 18 - improve the release process +### Step 17 - improve the release process Every release identifies new issues and ways that the process can be improved. diff --git a/assets/release_process/create_branch.png b/assets/release_process/create_branch.png deleted file mode 100644 index 8c1ae686e..000000000 Binary files a/assets/release_process/create_branch.png and /dev/null differ diff --git a/examples/operation-security.yml b/examples/operation-security.yml new file mode 100644 index 000000000..0ee3c26cc --- /dev/null +++ b/examples/operation-security.yml @@ -0,0 +1,106 @@ +asyncapi: 2.4.0 +info: + title: Notifications + version: 1.0.0 + description: >- + This contract defines HTTP Push notification for + application authorization revocation topic +channels: + AUTHORIZATION_REVOCATION: + subscribe: + message: + $ref: '#/components/messages/message' + bindings: + http: + type: request + method: POST + headers: + type: object + properties: + Content-Type: + type: string + enum: + - application/json + security: + petstore_auth: + - subscribe:auth_revocations +components: + messages: + message: + headers: + type: object + properties: + X-SIGNATURE: + description: ECC message signature + type: string + payload: + type: object + properties: + metadata: + $ref: '#/components/schemas/MetaData' + notification: + $ref: '#/components/schemas/Notification' + schemas: + MetaData: + type: object + properties: + topic: + type: string + description: Topic subscribed to. + schemaVersion: + type: string + description: The schema for this topic. + deprecated: + type: boolean + description: If this is a deprecated schema or topic. + default: 'false' + Notification: + type: object + properties: + notificationId: + type: string + description: The notification Id. + eventDate: + type: string + description: The event date associated with this notification in UTC. + publishDate: + type: string + description: The message publish date in UTC. + publishAttemptCount: + type: integer + description: The number of attempts made to publish this message. + data: + $ref: '#/components/schemas/AuthorizationRevocationData' + AuthorizationRevocationData: + type: object + description: The Authorization Revocation payload. + properties: + username: + type: string + description: The username for the user. + userId: + type: string + description: The immutable public userId for the user + eiasToken: + type: string + description: The legacy eiasToken specific to the user + revokeReason: + type: string + enum: + - REVOKED_BY_APP + - REVOKED_BY_USER + - REVOKED_BY_ADMIN + - PASSWORD_CHANGE + description: The reason for authorization revocation + revocationDate: + type: string + description: Date and time when the authorization was revoked + securitySchemes: + petstore_auth: + type: oauth2 + description: The oauth security descriptions + flows: + clientCredentials: + tokenUrl: 'https://example.com/api/oauth/dialog' + scopes: + subscribe:auth_revocations: Scope required for authorization revocation topic diff --git a/examples/social-media/common/messages.yaml b/examples/social-media/common/messages.yaml index 338251713..a4b267ac0 100644 --- a/examples/social-media/common/messages.yaml +++ b/examples/social-media/common/messages.yaml @@ -9,8 +9,8 @@ likeComment: commentChanged: description: Message that is being sent when a comment have been updated. payload: - $ref: './schemas.yaml#/commentChanged' + $ref: './schemas.yaml#/commentChangedPayload' updateCommentLikes: description: Message that is being sent when a comment have been updated. payload: - $ref: './schemas.yaml#/updateCommentLikesPayload' \ No newline at end of file + $ref: './schemas.yaml#/updateCommentLikesPayload' diff --git a/examples/streetlights-operation-security.yml b/examples/streetlights-operation-security.yml new file mode 100644 index 000000000..d75d9a371 --- /dev/null +++ b/examples/streetlights-operation-security.yml @@ -0,0 +1,212 @@ +asyncapi: '2.4.0' +info: + title: Streetlights Kafka API + version: '1.0.0' + description: | + The Smartylighting Streetlights API allows you to remotely manage the city lights. + + ### Check out its awesome features: + + * Turn a specific streetlight on/off 🌃 + * Dim a specific streetlight 😎 + * Receive real-time information about environmental lighting conditions 📈 + license: + name: Apache 2.0 + url: https://www.apache.org/licenses/LICENSE-2.0 + +servers: + test: + url: test.mykafkacluster.org:8092 + protocol: kafka-secure + description: Test broker + security: + - saslScram: [] + test_oauth: + url: test.mykafkacluster.org:8093 + protocol: kafka-secure + description: Test port for oauth + security: + - streetlights_auth: + - streetlights:write + - streetlights:read + + +defaultContentType: application/json + +channels: + smartylighting.streetlights.1.0.event.{streetlightId}.lighting.measured: + description: The topic on which measured values may be produced and consumed. + servers: + - test + parameters: + streetlightId: + $ref: '#/components/parameters/streetlightId' + publish: + summary: Inform about environmental lighting conditions of a particular streetlight. + operationId: receiveLightMeasurement + traits: + - $ref: '#/components/operationTraits/kafka' + message: + $ref: '#/components/messages/lightMeasured' + + smartylighting.streetlights.1.0.action.{streetlightId}.turn.on: + servers: + - test_oauth + parameters: + streetlightId: + $ref: '#/components/parameters/streetlightId' + subscribe: + operationId: turnOn + traits: + - $ref: '#/components/operationTraits/kafka' + message: + $ref: '#/components/messages/turnOnOff' + security: + # This operation level security implies the ability to subscribe to messages from + # `smartylighting.streetlights.1.0.action.{streetlightId}.turn.on` channel with Authorization headers + # that have `streetlights:read` scope. Note that an operation level security must still satisfy + # security requirements specified at the server level. + - streetlights_auth: + - streetlights:read + + smartylighting.streetlights.1.0.action.{streetlightId}.turn.off: + servers: + - test_oauth + parameters: + streetlightId: + $ref: '#/components/parameters/streetlightId' + subscribe: + operationId: turnOff + traits: + - $ref: '#/components/operationTraits/kafka' + message: + $ref: '#/components/messages/turnOnOff' + security: + # This operation level security implies the ability to subscribe to messages from + # `smartylighting.streetlights.1.0.action.{streetlightId}.turn.off` channel with Authorization headers + # that have `streetlights:read` scope. Note that an operation level security must still satisfy + # security options specified at the server level. + - streetlights_auth: + - streetlights:read + smartylighting.streetlights.1.0.action.{streetlightId}.dim: + servers: + - test_oauth + parameters: + streetlightId: + $ref: '#/components/parameters/streetlightId' + subscribe: + operationId: dimLight + traits: + - $ref: '#/components/operationTraits/kafka' + message: + $ref: '#/components/messages/dimLight' + security: + # This operation level security implies the ability to subscribe to messages from + # `smartylighting.streetlights.1.0.action.{streetlightId}.dim` channel with Authorization headers + # that have `streetlights:read` scope. Note that an operation level security must still satisfy + # security options specified at the server level. + - streetlights_auth: + - streetlights:read + + +components: + messages: + lightMeasured: + name: lightMeasured + title: Light measured + summary: Inform about environmental lighting conditions of a particular streetlight. + contentType: application/json + traits: + - $ref: '#/components/messageTraits/commonHeaders' + payload: + $ref: "#/components/schemas/lightMeasuredPayload" + turnOnOff: + name: turnOnOff + title: Turn on/off + summary: Command a particular streetlight to turn the lights on or off. + traits: + - $ref: '#/components/messageTraits/commonHeaders' + payload: + $ref: "#/components/schemas/turnOnOffPayload" + dimLight: + name: dimLight + title: Dim light + summary: Command a particular streetlight to dim the lights. + traits: + - $ref: '#/components/messageTraits/commonHeaders' + payload: + $ref: "#/components/schemas/dimLightPayload" + + schemas: + lightMeasuredPayload: + type: object + properties: + lumens: + type: integer + minimum: 0 + description: Light intensity measured in lumens. + sentAt: + $ref: "#/components/schemas/sentAt" + turnOnOffPayload: + type: object + properties: + command: + type: string + enum: + - on + - off + description: Whether to turn on or off the light. + sentAt: + $ref: "#/components/schemas/sentAt" + dimLightPayload: + type: object + properties: + percentage: + type: integer + description: Percentage to which the light should be dimmed to. + minimum: 0 + maximum: 100 + sentAt: + $ref: "#/components/schemas/sentAt" + sentAt: + type: string + format: date-time + description: Date and time when the message was sent. + + securitySchemes: + saslScram: + type: scramSha256 + description: Provide your username and password for SASL/SCRAM authentication + streetlights_auth: + type: oauth2 + description: The oauth security descriptions + flows: + clientCredentials: + tokenUrl: 'https://example.com/api/oauth/dialog' + scopes: + streetlights:read: Scope required for subscribing to channel + streetlights:write: Scope required for publishing to channel + + parameters: + streetlightId: + description: The ID of the streetlight. + schema: + type: string + + messageTraits: + commonHeaders: + headers: + type: object + properties: + my-app-header: + type: integer + minimum: 0 + maximum: 100 + + operationTraits: + kafka: + bindings: + kafka: + clientId: + type: string + enum: ['my-app-id'] diff --git a/mlc_config.json b/mlc_config.json new file mode 100644 index 000000000..01833db7f --- /dev/null +++ b/mlc_config.json @@ -0,0 +1,19 @@ +{ + "ignorePatterns": [ + { + "pattern": "^https://github.com/asyncapi/spec/tree/BRANCH_NAME" + }, + { + "pattern": "^https://github.com/asyncapi/spec-json-schemas/tree/BRANCH_NAME" + }, + { + "pattern": "^https://github.com/asyncapi/parser-js/tree/BRANCH_NAME" + }, + { + "pattern": "^https://github.com/asyncapi/website/pull/PULLREQUEST" + }, + { + "pattern": "^https://github.com/asyncapi/spec/blob/.*.md$" + } + ] +} diff --git a/spec/asyncapi.md b/spec/asyncapi.md index b440554da..00f4d021c 100644 --- a/spec/asyncapi.md +++ b/spec/asyncapi.md @@ -34,6 +34,7 @@ It means that the [application](#definitionsApplication) allows [consumers](#def - [Definitions](#definitions) + - [Server](#definitionsServer) - [Application](#definitionsApplication) - [Producer](#definitionsProducer) - [Consumer](#definitionsConsumer) @@ -84,20 +85,23 @@ It means that the [application](#definitionsApplication) allows [consumers](#def ## Definitions +#### Server +A server MAY be a message broker that is capable of sending and/or receiving between a [producer](#definitionsProducer) and [consumer](#definitionsConsumer). A server MAY be a service with WebSocket API that enables message-driven communication between browser-to-server or server-to-server. + #### Application -An application is any kind of computer program or a group of them. It MUST be a [producer](#definitionsProducer), a [consumer](#definitionsConsumer) or both. An application MAY be a microservice, IoT device (sensor), mainframe process, etc. An application MAY be written in any number of different programming languages as long as they support the selected [protocol](#definitionsProtocol). An application MUST also use a protocol supported by the server in order to connect and exchange [messages](#definitionsMessage). +An application is any kind of computer program or a group of them. It MUST be a [producer](#definitionsProducer), a [consumer](#definitionsConsumer) or both. An application MAY be a microservice, IoT device (sensor), mainframe process, etc. An application MAY be written in any number of different programming languages as long as they support the selected [protocol](#definitionsProtocol). An application MUST also use a protocol supported by the [server](#definitionsServer) in order to connect and exchange [messages](#definitionsMessage). #### Producer -A producer is a type of application, connected to a server, that is creating [messages](#definitionsMessage) and addressing them to [channels](#definitionsChannel). A producer MAY be publishing to multiple channels depending on the server, protocol, and use-case pattern. +A producer is a type of application, connected to a [server](#definitionsServer), that is creating [messages](#definitionsMessage) and addressing them to [channels](#definitionsChannel). A producer MAY be publishing to multiple channels depending on the [server](#definitionsServer), protocol, and use-case pattern. #### Consumer -A consumer is a type of application, connected to a server via a supported [protocol](#definitionsProtocol), that is consuming [messages](#definitionsMessage) from [channels](#definitionsChannel). A consumer MAY be consuming from multiple channels depending on the server, protocol, and the use-case pattern. +A consumer is a type of application, connected to a [server](#definitionsServer) via a supported [protocol](#definitionsProtocol), that is consuming [messages](#definitionsMessage) from [channels](#definitionsChannel). A consumer MAY be consuming from multiple channels depending on the [server](#definitionsServer), protocol, and the use-case pattern. #### Message -A message is the mechanism by which information is exchanged via a channel between servers and applications. A message MUST contain a payload and MAY also contain headers. The headers MAY be subdivided into [protocol](#definitionsProtocol)-defined headers and header properties defined by the application which can act as supporting metadata. The payload contains the data, defined by the application, which MUST be serialized into a format (JSON, XML, Avro, binary, etc.). Since a message is a generic mechanism, it can support multiple interaction patterns such as event, command, request, or response. +A message is the mechanism by which information is exchanged via a channel between [servers](#definitionsServer) and applications. A message MUST contain a payload and MAY also contain headers. The headers MAY be subdivided into [protocol](#definitionsProtocol)-defined headers and header properties defined by the application which can act as supporting metadata. The payload contains the data, defined by the application, which MUST be serialized into a format (JSON, XML, Avro, binary, etc.). Since a message is a generic mechanism, it can support multiple interaction patterns such as event, command, request, or response. #### Channel -A channel is an addressable component, made available by the server, for the organization of [messages](#definitionsMessage). [Producer](#definitionsProducer) applications send messages to channels and [consumer](#definitionsConsumer) applications consume messages from channels. Servers MAY support many channel instances, allowing messages with different content to be addressed to different channels. Depending on the server implementation, the channel MAY be included in the message via protocol-defined headers. +A channel is an addressable component, made available by the [server](#definitionsServer), for the organization of [messages](#definitionsMessage). [Producer](#definitionsProducer) applications send messages to channels and [consumer](#definitionsConsumer) applications consume messages from channels. [Servers](#definitionsServer) MAY support many channel instances, allowing messages with different content to be addressed to different channels. Depending on the [server](#definitionsServer) implementation, the channel MAY be included in the message via protocol-defined headers. #### Protocol A protocol is the mechanism (wireline protocol or API) by which [messages](#definitionsMessage) are exchanged between the application and the [channel](#definitionsChannel). Example protocols include, but are not limited to, AMQP, HTTP, JMS, Kafka, Anypoint MQ, MQTT, Solace, STOMP, Mercure, WebSocket. @@ -319,7 +323,7 @@ The Servers Object is a map of [Server Objects](#serverObject). Field Pattern | Type | Description ---|:---:|--- -`^[A-Za-z0-9_\-]+$` | [Server Object](#serverObject) | The definition of a server this application MAY connect to. +`^[A-Za-z0-9_\-]+$` | [Server Object](#serverObject) \| [Reference Object](#referenceObject) | The definition of a server this application MAY connect to. ##### Servers Object Example @@ -703,7 +707,8 @@ Field Name | Type | Description ---|:---:|--- operationId | `string` | Unique string used to identify the operation. The id MUST be unique among all operations described in the API. The operationId value is **case-sensitive**. Tools and libraries MAY use the operationId to uniquely identify an operation, therefore, it is RECOMMENDED to follow common programming naming conventions. summary | `string` | A short summary of what the operation is about. -description | `string` | A verbose explanation of the operation. [CommonMark syntax](https://spec.commonmark.org/) can be used for rich text representation. +description | `string` | A verbose explanation of the operation. [CommonMark syntax](http://spec.commonmark.org/) can be used for rich text representation. +security | [[Security Requirement Object](#securityRequirementObject)]| A declaration of which security mechanisms are associated with this operation. Only one of the security requirement objects MUST be satisfied to authorize an operation. In cases where Server Security also applies, it MUST also be satisfied. tags | [Tags Object](#tagsObject) | A list of tags for API documentation control. Tags can be used for logical grouping of operations. externalDocs | [External Documentation Object](#externalDocumentationObject) | Additional external documentation for this operation. bindings | [Operation Bindings Object](#operationBindingsObject) \| [Reference Object](#referenceObject) | A map where the keys describe the name of the protocol and the values describe protocol-specific definitions for the operation. @@ -719,6 +724,14 @@ This object can be extended with [Specification Extensions](#specificationExtens "operationId": "registerUser", "summary": "Action to sign a user up.", "description": "A longer description", + "security": [ + { + "petstore_auth": [ + "write:pets", + "read:pets" + ] + } + ], "tags": [ { "name": "user" }, { "name": "signup" }, @@ -761,6 +774,10 @@ This object can be extended with [Specification Extensions](#specificationExtens operationId: registerUser summary: Action to sign a user up. description: A longer description +security: + - petstore_auth: + - write:pets + - read:pets tags: - name: user - name: signup @@ -802,6 +819,7 @@ Field Name | Type | Description operationId | `string` | Unique string used to identify the operation. The id MUST be unique among all operations described in the API. The operationId value is **case-sensitive**. Tools and libraries MAY use the operationId to uniquely identify an operation, therefore, it is RECOMMENDED to follow common programming naming conventions. summary | `string` | A short summary of what the operation is about. description | `string` | A verbose explanation of the operation. [CommonMark syntax](https://spec.commonmark.org/) can be used for rich text representation. +security | [[Security Requirement Object](#securityRequirementObject)]| A declaration of which security mechanisms are associated with this operation. Only one of the security requirement objects MUST be satisfied to authorize an operation. In cases where Server Security also applies, it MUST also be satisfied. tags | [Tags Object](#tagsObject) | A list of tags for API documentation control. Tags can be used for logical grouping of operations. externalDocs | [External Documentation Object](#externalDocumentationObject) | Additional external documentation for this operation. bindings | [Operation Bindings Object](#operationBindingsObject) \| [Reference Object](#referenceObject) | A map where the keys describe the name of the protocol and the values describe protocol-specific definitions for the operation. @@ -1064,6 +1082,7 @@ Describes a message received on a given channel and operation. Field Name | Type | Description ---|:---:|--- +messageId | `string` | Unique string used to identify the message. The id MUST be unique among all messages described in the API. The messageId value is **case-sensitive**. Tools and libraries MAY use the messageId to uniquely identify a message, therefore, it is RECOMMENDED to follow common programming naming conventions. headers | [Schema Object](#schemaObject) | [Reference Object](#referenceObject) | Schema definition of the application headers. Schema MUST be of type "object". It **MUST NOT** define the protocol headers. payload | `any` | Definition of the message payload. It can be of any type but defaults to [Schema object](#schemaObject). It must match the schema format, including encoding type - e.g Avro should be inlined as either a YAML or JSON object NOT a string to be parsed as YAML or JSON. correlationId | [Correlation ID Object](#correlationIdObject) | [Reference Object](#referenceObject) | Definition of the correlation ID used for message tracing or matching. @@ -1103,6 +1122,7 @@ Name | Allowed values | Notes ```json { + "messageId": "userSignup", "name": "UserSignup", "title": "User signup", "summary": "Action to sign a user up.", @@ -1166,6 +1186,7 @@ Name | Allowed values | Notes ``` ```yaml +messageId: userSignup name: UserSignup title: User signup summary: Action to sign a user up. @@ -1213,6 +1234,7 @@ Example using Avro to define the payload: ```json { + "messageId": "userSignup", "name": "UserSignup", "title": "User signup", "summary": "Action to sign a user up.", @@ -1230,6 +1252,7 @@ Example using Avro to define the payload: ``` ```yaml +messageId: userSignup name: UserSignup title: User signup summary: Action to sign a user up. @@ -1259,6 +1282,7 @@ If you're looking to apply traits to an operation, see the [Operation Trait Obje Field Name | Type | Description ---|:---:|--- +messageId | `string` | Unique string used to identify the message. The id MUST be unique among all messages described in the API. The messageId value is **case-sensitive**. Tools and libraries MAY use the messageId to uniquely identify a message, therefore, it is RECOMMENDED to follow common programming naming conventions. headers | [Schema Object](#schemaObject) | [Reference Object](#referenceObject) | Schema definition of the application headers. Schema MUST be of type "object". It **MUST NOT** define the protocol headers. correlationId | [Correlation ID Object](#correlationIdObject) | [Reference Object](#referenceObject) | Definition of the correlation ID used for message tracing or matching. schemaFormat | `string` | A string containing the name of the schema format/language used to define the message payload. If omitted, implementations should parse the payload as a [Schema object](#schemaObject). @@ -1439,6 +1463,7 @@ Field Name | Type | Description ---|:---|--- schemas | Map[`string`, [Schema Object](#schemaObject) \| [Reference Object](#referenceObject)] | An object to hold reusable [Schema Objects](#schemaObject). servers | Map[`string`, [Server Object](#serverObject) \| [Reference Object](#referenceObject)] | An object to hold reusable [Server Objects](#serverObject). + serverVariables | Map[`string`, [Server Variable Object](#serverVariableObject) \| [Reference Object](#referenceObject)] | An object to hold reusable [Server Variable Objects](#serverVariableObject). channels | Map[`string`, [Channel Item Object](#channelItemObject)] | An object to hold reusable [Channel Item Objects](#channelItemObject). messages | Map[`string`, [Message Object](#messageObject) \| [Reference Object](#referenceObject)] | An object to hold reusable [Message Objects](#messageObject). securitySchemes| Map[`string`, [Security Scheme Object](#securitySchemeObject) \| [Reference Object](#referenceObject)] | An object to hold reusable [Security Scheme Objects](#securitySchemeObject). @@ -1498,10 +1523,28 @@ my.org.User }, "servers": { "development": { - "url": "development.gigantic-server.com", + "url": "{stage}.gigantic-server.com:{port}", "description": "Development server", "protocol": "amqp", - "protocolVersion": "0.9.1" + "protocolVersion": "0.9.1", + "variables": { + "stage": { + "$ref": "#/components/serverVariables/stage" + }, + "port": { + "$ref": "#/components/serverVariables/port" + } + } + } + }, + "serverVariables": { + "stage": { + "default": "demo", + "description": "This value is assigned by the service provider, in this example `gigantic-server.com`" + }, + "port": { + "enum": ["8883", "8884"], + "default": "8883" } }, "channels": { @@ -1600,10 +1643,22 @@ components: type: string servers: development: - url: development.gigantic-server.com + url: "{stage}.gigantic-server.com:{port}" description: Development server protocol: amqp protocolVersion: 0.9.1 + variables: + stage: + $ref: "#/components/serverVariables/stage" + port: + $ref: "#/components/serverVariables/port" + serverVariables: + stage: + default: demo + description: This value is assigned by the service provider, in this example `gigantic-server.com` + port: + enum: [8883, 8884] + default: 8883 channels: user/signedup: subscribe: @@ -1840,10 +1895,12 @@ additionalProperties: "required": [ "name" ], - "example": { - "name": "Puma", - "id": 1 - } + "examples": [ + { + "name": "Puma", + "id": 1 + } + ] } ``` @@ -1857,8 +1914,8 @@ properties: type: string required: - name -example: - name: Puma +examples: +- name: Puma id: 1 ```