diff --git a/.gitattributes b/.gitattributes new file mode 100644 index 0000000000..a252d3d74c --- /dev/null +++ b/.gitattributes @@ -0,0 +1 @@ +*.md linguist-detectable diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS new file mode 100644 index 0000000000..baf749a51a --- /dev/null +++ b/.github/CODEOWNERS @@ -0,0 +1,11 @@ +# Global Repo Owners +* @oai/openapi-maintainers @oai/tsc + +# Specification Versions +/versions/ @oai/tsc + +# Protect specific top level files +/MAINTAINERS.md @oai/tsc +/TOB.md @oai/tsc +/GOVERNANCE.md @oai/tsc +/LICENSE @oai/tsc \ No newline at end of file diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml new file mode 100644 index 0000000000..4c65a29d77 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/config.yml @@ -0,0 +1,18 @@ +blank_issues_enabled: false + +contact_links: + - name: Have a question about using OpenAPI? + url: https://communityinviter.com/apps/open-api/openapi + about: Ask us on our Slack! + - name: Have a question about OpenAPI Tooling? + url: https://tools.openapis.org/ + about: Please ask your tooling vendor! + - name: Want to add to our list of OpenAPI Tools? + url: https://tools.openapis.org/ + about: Please take a look at our tooling site's instructions! + - name: Want to suggest more how-to documentation and examples? + url: https://github.com/OAI/learn.openapis.org/issues/new + about: Please open an issue on our learning site! + - name: Want to request a new feature in the specification? + url: https://github.com/OAI/OpenAPI-Specification/discussions/new?category=enhancements + about: Please start a discussion in this repository! diff --git a/.github/ISSUE_TEMPLATE/registry_feature_request.md b/.github/ISSUE_TEMPLATE/registry_feature_request.md new file mode 100644 index 0000000000..5c8d9a6394 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/registry_feature_request.md @@ -0,0 +1,25 @@ +--- +name: Contribute to the registries at spec.openapis.org/registry +about: Add a new registry entry, or edit an existing one +title: 'Registry: ...' +labels: registries +assignees: '' + +--- + +**Which registry do you want to contribute to** +- [ ] [Alternative Schema Type Registry](https://spec.openapis.org/registry/alternative-schema) +- [ ] [Draft Features Registry](https://spec.openapis.org/registry/draft-feature) +- [ ] [Specification Extension Registry](https://spec.openapis.org/registry/extension) +- [ ] [Format Registry](https://spec.openapis.org/registry/format) +- [ ] [Extension Namespace Registry](https://spec.openapis.org/registry/namespace) +- [ ] [Tag Kind Registry](https://spec.openapis.org/registry/tag-kind) + +**Describe your contribution** +A clear and concise description of what you want to add or change. + +**Describe alternatives you've considered** +A clear and concise description of any alternative solutions or features you've considered. + +**Additional context** +Add any other context or screenshots about the feature request here. diff --git a/.github/ISSUE_TEMPLATE/spec_bug_report.md b/.github/ISSUE_TEMPLATE/spec_bug_report.md new file mode 100644 index 0000000000..c642b83569 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/spec_bug_report.md @@ -0,0 +1,18 @@ +--- +name: Report an error in the specification +about: Create a report to help us improve the specification +title: 'vX.Y: ...' +labels: '' +assignees: '' + +--- + +**Describe the error in the specification** +A clear and concise description of +- what the error is, +- which specification versions are affected, +- what you would expect the specification to say instead, and +- a link to the corresponding specification section in the "oldest" affected version. + +**Additional context** +Add any other context about the problem here. diff --git a/.github/dependabot.yml b/.github/dependabot.yml new file mode 100644 index 0000000000..ae17f3da25 --- /dev/null +++ b/.github/dependabot.yml @@ -0,0 +1,12 @@ +version: 2 +updates: +- package-ecosystem: github-actions + directory: "/" + schedule: + interval: daily + open-pull-requests-limit: 10 +- package-ecosystem: npm + directory: "/" + schedule: + interval: daily + open-pull-requests-limit: 10 diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md new file mode 100644 index 0000000000..e636e84419 --- /dev/null +++ b/.github/pull_request_template.md @@ -0,0 +1,21 @@ + + + + +- [ ] schema changes are included in this pull request +- [ ] schema changes are needed for this pull request but not done yet +- [ ] no schema changes are needed for this pull request diff --git a/.github/templates/agenda.md b/.github/templates/agenda.md new file mode 100644 index 0000000000..3e64fa498a --- /dev/null +++ b/.github/templates/agenda.md @@ -0,0 +1,36 @@ +## Weekly meetings happen on Thursdays at 9am - 10am Pacific + +This agenda gives visibility into discussion topics for the weekly Technical Developer Community (TDC) meetings. Sharing agenda items in advance allows people to plan to attend meetings where they have an interest in specific topics. + +Whether attending or not, **anyone can comment on this issue prior to the meeting to suggest topics or to add comments on planned topics or proposals**. + +Meetings take place over Zoom: [https://zoom.us/j/975841675](https://zoom.us/j/975841675?pwd=SUh4MjRLaEFKNlI3RElpWTdhRDVVUT09), dial-in passcode: 763054 + +### Accessibility & Etiquette +* Participants must abide by our [Code-of-Conduct](https://github.com/OAI/OpenAPI-Specification?tab=coc-ov-file). + +* Meetings are recorded for future reference, and for those who are not able to attend in-person. + +* We invite you to feel comfortable to challenge any language or behaviour that is harmful or not inclusive during this meeting. + +* We look forward to your participation, but please consider these acts of etiquette: + * Remain on mute when not speaking to prevent interruptions. + * Blur your background to reduce visual distractions. + * Use the Zoom meeting "Raise Hand" feature to notify the group when you wish to speak. + +| Blur My Background | Raise Hand | +|-|-| +| Screenshot of Zoom UI showing the 'Stop Video' and 'Blur My Background' control | Screenshot of Zoom UI showing the 'Reaction' and 'Raise Hand' control | + +### Agenda Structure + +| Topic | Owner | Decision/NextStep | +|-|-|-| +Intros and governance meta-topics (5 mins) | TDC | | +Reports from Special Interest Groups (5 mins) | SIG members | | +Any other business (add comments below to suggest topics) | TDC | | +[Approved spec PRs](https://github.com/OAI/OpenAPI-Specification/pulls?q=is%3Apr+is%3Aopen+review%3Aapproved) | @OAI/tsc | | +[Active Projects](https://github.com/OAI/OpenAPI-Specification/projects?query=is%3Aopen) | @OAI/openapi-maintainers | | +[New issues needing attention](https://github.com/search?q=repo%3Aoai%2Fopenapi-specification+is%3Aissue+comments%3A0+no%3Alabel+is%3Aopen) | @OAI/triage | | + +/cc [@OAI/tsc](https://github.com/orgs/OAI/teams/tsc) please suggest items for inclusion. diff --git a/.github/workflows/agenda.yaml b/.github/workflows/agenda.yaml new file mode 100644 index 0000000000..88b9be8391 --- /dev/null +++ b/.github/workflows/agenda.yaml @@ -0,0 +1,47 @@ +name: agenda + +# author: @MikeRalphson +# issue: various + +# +# This workflow creates the agenda issue each week. It runs on a cron every +# Monday morning, raising an issue for the following Thursday. +# It can also be run manually, in case GitHub Actions has a failure. +# + +on: + schedule: + - cron: '0 16 * * 4' + workflow_dispatch: {} + +permissions: + issues: write + contents: read + +jobs: + agenda: + if: github.repository == 'OAI/OpenAPI-Specification' + env: + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} + TITLE_PREFIX: "Open Community (TDC) Meeting, " + LABEL: "Housekeeping" + POST_MEETING_CLOSE_DURATION_IN_DAYS: 10 + + runs-on: ubuntu-latest + + steps: + - uses: actions/checkout@v4 # checkout repo content + + # we want to close old agenda issues before creating a new one because there's a limit of 3 pinned items on a repo + - name: Close old agenda issues + run: gh issue list -l ${{ env.LABEL }} --author "app/github-actions" --json number,title | ConvertFrom-Json | Where-Object { $_.title -like "${{ env.TITLE_PREFIX }}*" -and ([datetime]::UtcNow - [datetime]::Parse([regex]::Replace($_.title.Replace("${{ env.TITLE_PREFIX }}", ""), "\([^)]+\)", ""))) -ge [timespan]::FromDays([int]::Parse("${{ env.POST_MEETING_CLOSE_DURATION_IN_DAYS }}"))} | ForEach-Object { gh issue close $_.number && gh issue unpin $_.number } + shell: pwsh + + - name: Create agenda issue + run: | + $nextThursday = @(@(1..8) | % {$(Get-Date).AddDays($_)} | ? {$_.DayOfWeek -ieq "Thursday"})[0].ToString("dddd dd MMMM yyyy", [CultureInfo]::InvariantCulture) + $result = gh issue create -l ${{ env.LABEL }} -t "${{ env.TITLE_PREFIX }}$nextThursday" -F .github/templates/agenda.md + gh issue pin $result + shell: pwsh + + diff --git a/.github/workflows/check-restricted-files.yaml b/.github/workflows/check-restricted-files.yaml new file mode 100644 index 0000000000..ec625c7de4 --- /dev/null +++ b/.github/workflows/check-restricted-files.yaml @@ -0,0 +1,44 @@ +name: check-restricted-files + +# Author: @ralfhandl +# Issue: https://github.com/OAI/OpenAPI-Specification/issues/3432 + +# This workflow fails if restricted files are changed in a pull request + +on: + pull_request: + paths: + - 'schemas/**/*.yaml' + - 'versions/*.md' + +jobs: + check-files: + runs-on: ubuntu-latest + steps: + - name: Check changed files + shell: bash + run: | + if [[ "${{ github.event.pull_request.head.repo.full_name }}" == "OAI/OpenAPI-Specification" ]] && \ + [[ "${{ github.event.pull_request.base.repo.full_name }}" == "OAI/OpenAPI-Specification" ]]; then + + if [[ "${{ github.event.pull_request.head.ref }}" == "main" ]] && \ + [[ "${{ github.event.pull_request.base.ref }}" == "dev" ]]; then + echo Sync from main to dev + exit 0 + fi + + if [[ "${{ github.event.pull_request.head.ref }}" == "dev" ]] && \ + [[ "${{ github.event.pull_request.base.ref }}" =~ ^v[0-9]+\.[0-9]+-dev$ ]]; then + echo Sync from dev to ${{ github.event.pull_request.base.ref }} + exit 0 + fi + + if [[ "${{ github.event.pull_request.head.ref }}" =~ ^v[0-9]+\.[0-9]+\.[0-9]+-rel$ ]] && \ + [[ "${{ github.event.pull_request.base.ref }}" == "main" ]]; then + echo Release from ${{ github.event.pull_request.head.ref }} to main + exit 0 + fi + fi + + echo This PR contains changes to files that should not be changed + exit 1 diff --git a/.github/workflows/inactive-issues.yml b/.github/workflows/inactive-issues.yml new file mode 100644 index 0000000000..06b3c028bd --- /dev/null +++ b/.github/workflows/inactive-issues.yml @@ -0,0 +1,36 @@ +on: + issues: + types: labeled + workflow_dispatch: + schedule: + - cron: '*/5 * * * *' + +permissions: + issues: write + contents: read + +name: Label and close issues with no recent activity + +env: + GH_TOKEN: ${{ secrets.GITHUB_TOKEN }} + NEEDS_ATTENTION_LABEL: "Needs attention" + NEEDS_AUTHOR_FEEDBACK_LABEL: "Needs author feedback" + NO_RECENT_ACTIVITY_LABEL: "No recent activity" + NO_RECENT_ACTIVITY_DURATION_IN_DAYS: 7 + NO_RECENT_ACTIVITY_DURATION_CLOSE_IN_DAYS: 28 + ORG_NAME: ${{ github.repository_owner }} + REPO_NAME: ${{ github.event.repository.name }} + NO_RECENT_ACTIVITY_COMMENT: "This issue has been labeled with `No recent activity` because there has been no recent activity. It will be closed if no further activity occurs within 28 days. Please re-open this issue or open a new one after this delay if you need to." + + +jobs: + run: + if: github.repository == 'OAI/OpenAPI-Specification' + runs-on: ubuntu-latest + name: Label issues with no recent activity + steps: + - uses: actions/checkout@v4 + - run: scripts/label-no-recent.ps1 + shell: pwsh + - run: scripts/close-no-recent.ps1 + shell: pwsh diff --git a/.github/workflows/respec.yaml b/.github/workflows/respec.yaml new file mode 100644 index 0000000000..e5982c9812 --- /dev/null +++ b/.github/workflows/respec.yaml @@ -0,0 +1,59 @@ +name: respec + +# author: @MikeRalphson +# issue: https://github.com/OAI/OpenAPI-Specification/issues/1564 + +# +# This workflow updates the respec 'pretty' rendered versions of the spec +# on the gh-pages branch when the corresponding markdown files change. +# + +# run this manually from main +on: + workflow_dispatch: {} + +jobs: + respec: + if: github.ref == 'refs/heads/main' + + runs-on: ubuntu-latest + + steps: + - uses: actions/checkout@v4 # checkout main branch + with: + fetch-depth: 0 + + - uses: actions/setup-node@v4 # setup Node.js + with: + node-version: '20.x' + + - name: Install dependencies + run: npm ci + + - uses: actions/checkout@v4 # checkout gh-pages branch + with: + ref: gh-pages + path: deploy + + - name: run main script + run: scripts/md2html/build.sh + + - name: Create Pull Request + uses: peter-evans/create-pull-request@v6 + with: + token: ${{ secrets.GITHUB_TOKEN }} + branch: update-respec-version + base: gh-pages + delete-branch: true + path: deploy + labels: Housekeeping + reviewers: darrelmiller,webron,earth2marsh,webron,lornajane,mikekistler,miqui,ralfhandl,handrews,karenetheridge + title: Update ReSpec-rendered specification versions + commit-message: Update ReSpec-rendered specification versions + signoff: true + body: | + This pull request is automatically triggered by GitHub action `respec`. + + The `versions/*.md` files have changed, so the HTML files are automatically being regenerated. + + diff --git a/.github/workflows/schema-publish.yaml b/.github/workflows/schema-publish.yaml new file mode 100644 index 0000000000..568990ea6e --- /dev/null +++ b/.github/workflows/schema-publish.yaml @@ -0,0 +1,61 @@ +name: schema-publish + +# author: @ralfhandl +# issue: https://github.com/OAI/OpenAPI-Specification/issues/3715 + +# +# This workflow creates a pull request for publishing schema iterations to the gh-pages branch +# + +# run this on push to vX.Y-dev branches or manually +on: + push: + branches: + - 'v[0-9].[0-9]-dev' + paths: + - 'src/schemas/validation/*.yaml' + - 'scripts/schema-publish.sh' + - '.github/workflows/schema-publish.yaml' + workflow_dispatch: {} + +jobs: + publish: + + runs-on: ubuntu-latest + + steps: + - uses: actions/checkout@v4 # checkout main branch + with: + fetch-depth: 0 + + - uses: actions/setup-node@v4 # setup Node.js + with: + node-version: '22.x' + + - name: Install dependencies + run: npm ci + + - uses: actions/checkout@v4 # checkout gh-pages branch + with: + ref: gh-pages + path: deploy + + - name: run main script + run: scripts/schema-publish.sh + + - name: Create Pull Request + uses: peter-evans/create-pull-request@v6 + with: + token: ${{ secrets.GITHUB_TOKEN }} + branch: ${{ github.ref_name }}-publish-schema-iteration + base: gh-pages + delete-branch: true + path: deploy + labels: Housekeeping,Schema + reviewers: darrelmiller,webron,earth2marsh,webron,lornajane,mikekistler,miqui,ralfhandl,handrews,karenetheridge + title: '${{ github.ref_name }}: publish OpenAPI schema iterations' + commit-message: New OpenAPI schema iterations + signoff: true + body: | + This pull request is automatically generated by GitHub action `schema-publish`. + The `src/schemas/validation/*.yaml` files have changed and JSON files are automatically generated. diff --git a/.github/workflows/schema-tests.yaml b/.github/workflows/schema-tests.yaml new file mode 100644 index 0000000000..7a3116936d --- /dev/null +++ b/.github/workflows/schema-tests.yaml @@ -0,0 +1,36 @@ +name: schema-test + +# Author: @MikeRalphson / runs @jdesrosiers tests +# Issue: https://github.com/OAI/OpenAPI-Specification/pull/2489 + +# +# This workflow runs the npm test script to validate passing and failing +# testcases for the metaschemas +# + +# run this on push to any branch and creation of pull-requests +on: + pull_request: {} + workflow_dispatch: {} + +jobs: + test: + + runs-on: ubuntu-latest + + steps: + - uses: actions/checkout@v4 # checkout repo content + with: + fetch-depth: 0 + + - uses: actions/setup-node@v4 # setup Node.js + with: + node-version: '20.x' + + - name: Install dependencies + run: npm ci + + - name: Run tests + run: npm run test + env: + BASE: ${{ github.event.pull_request.base.ref }} diff --git a/.github/workflows/sync-dev-to-vX.Y-dev.yaml b/.github/workflows/sync-dev-to-vX.Y-dev.yaml new file mode 100644 index 0000000000..1ac07e2d13 --- /dev/null +++ b/.github/workflows/sync-dev-to-vX.Y-dev.yaml @@ -0,0 +1,52 @@ +name: sync-dev-to-vX.Y-dev + +# author: @ralfhandl + +# +# This workflow creates PRs to update the vX.Y-dev branch with the latest changes from dev +# + +# run this on push to dev +on: + push: + branches: + - dev + +jobs: + sync-branches: + runs-on: ubuntu-latest + steps: + - name: Generate access token + id: generate-token + uses: actions/create-github-app-token@v2 + with: + app-id: ${{ secrets.OAI_SPEC_PUBLISHER_APPID }} + private-key: ${{ secrets.OAI_SPEC_PUBLISHER_PRIVATE_KEY }} + + - name: Checkout repository + uses: actions/checkout@v4 + with: + fetch-depth: 0 + + - name: Create pull requests + id: pull_requests + shell: bash + run: | + DEV_BRANCHES=$(git branch -r --list origin/v?.?-dev) + for DEV_BRANCH in $DEV_BRANCHES; do + BASE=${DEV_BRANCH:7} + EXISTS=$(gh pr list --base $BASE --head $HEAD \ + --json number --jq '.[] | .number') + if [ ! -z "$EXISTS" ]; then + echo "PR #$EXISTS already wants to merge $HEAD into $BASE" + continue + fi + + gh pr create --base $BASE --head $HEAD \ + --label "Housekeeping" \ + --title "$BASE: update from $HEAD" \ + --body "Merge \`$HEAD\` into \`$BASE\`." + done + env: + GH_TOKEN: ${{ steps.generate-token.outputs.token }} + HEAD: dev diff --git a/.github/workflows/sync-main-to-dev.yaml b/.github/workflows/sync-main-to-dev.yaml new file mode 100644 index 0000000000..792f752947 --- /dev/null +++ b/.github/workflows/sync-main-to-dev.yaml @@ -0,0 +1,47 @@ +name: sync-main-to-dev + +# author: @ralfhandl + +# +# This workflow creates PRs to update the dev branch with the latest changes from main +# + +# run this on push to main +on: + push: + branches: + - main + +jobs: + sync-branch: + runs-on: ubuntu-latest + steps: + - name: Generate access token + id: generate-token + uses: actions/create-github-app-token@v2 + with: + app-id: ${{ secrets.OAI_SPEC_PUBLISHER_APPID }} + private-key: ${{ secrets.OAI_SPEC_PUBLISHER_PRIVATE_KEY }} + + - name: Checkout repository + uses: actions/checkout@v4 + + - name: Create pull request + id: pull_request + shell: bash + run: | + EXISTS=$(gh pr list --base $BASE --head $HEAD \ + --json number --jq '.[] | .number') + if [ ! -z "$EXISTS" ]; then + echo "PR #$EXISTS already wants to merge $HEAD into $BASE" + exit 0 + fi + + gh pr create --base $BASE --head $HEAD \ + --label "Housekeeping" \ + --title "$BASE: update from $HEAD" \ + --body "Merge \`$HEAD\` into \`$BASE\`." + env: + GH_TOKEN: ${{ steps.generate-token.outputs.token }} + HEAD: main + BASE: dev diff --git a/.github/workflows/validate-markdown.yaml b/.github/workflows/validate-markdown.yaml new file mode 100644 index 0000000000..115b57f4f6 --- /dev/null +++ b/.github/workflows/validate-markdown.yaml @@ -0,0 +1,33 @@ +name: validate-markdown + +# Author: @MikeRalphson +# Issue: https://github.com/OAI/OpenAPI-Specification/issues/2130 + +# +# This workflow validates markdown files in the project root. +# It also validates the work-in-progress specification file src/oas.md with slightly different rules. +# + +# run this on push to any branch and creation of pull-requests +on: [push, pull_request] + +jobs: + lint: + + runs-on: ubuntu-latest + + steps: + + - uses: actions/checkout@v4 # checkout repo content + with: + fetch-depth: 0 + + - uses: actions/setup-node@v4 # setup Node.js + with: + node-version: '20.x' + + - name: Lint work-in-progress spec + run: npx --yes markdownlint-cli2 --config spec.markdownlint.yaml src/oas.md + + - name: Lint other files + run: npx --yes markdownlint-cli2 *.md diff --git a/.gitignore b/.gitignore index 88e134ab28..0bbd5a8cb8 100644 --- a/.gitignore +++ b/.gitignore @@ -5,4 +5,8 @@ target atlassian-ide-plugin.xml node_modules/ +deploy/ +deploy-preview/ +coverage/ +_site/ Gemfile.lock diff --git a/fixtures/v2.0/yaml/.gitkeep b/.gitmodules similarity index 100% rename from fixtures/v2.0/yaml/.gitkeep rename to .gitmodules diff --git a/.markdownlint.yaml b/.markdownlint.yaml new file mode 100644 index 0000000000..f7a1f2fcfd --- /dev/null +++ b/.markdownlint.yaml @@ -0,0 +1,33 @@ +# First heading is a top-level heading +MD002: true + +# Heading style (ATX is leading # symbols) +MD003: + style: atx + +# Unordered list symbol can be anything +MD004: false + +# Unordered list indentation size +MD007: + indent: 2 + +# Allow additional blank lines +MD012: false + +# Maximum line length +MD013: + line_length: 800 + tables: false + +# Headings need blank lines before and after +MD022: true + +# Duplicate headings are allowed +MD024: false + +# Surround lists with blank lines +MD032: true + +# Allow inline HTML +MD033: false diff --git a/.travis.yml b/.travis.yml deleted file mode 100644 index 822a22279c..0000000000 --- a/.travis.yml +++ /dev/null @@ -1,19 +0,0 @@ -sudo: false -script: - - npm install -env: - - VALIDATORS=tv4 - - VALIDATORS=zschema -matrix: - allow_failures: - - env: VALIDATORS=tv4 -install: - - rm -rf ~/.nvm - - mkdir -p ~/.nvm - - curl -L https://raw.githubusercontent.com/creationix/nvm/master/install.sh | sh - - source ~/.nvm/nvm.sh - - nvm install 8 - - nvm use 8 -script: - - npm install - - node node_modules/mdv/mdv versions/3.*.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000000..6ce59533a0 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,527 @@ +# Contribute to the OpenAPI Specification + +## Key information + +This project is covered by our [Code of Conduct](https://github.com/OAI/OpenAPI-Specification?tab=coc-ov-file#readme). +All participants are expected to read and follow this code. + +No changes, however trivial, are ever made to the contents of published specifications (the files in the `versions/` folder). +Exceptions may be made when links to external URLs have been changed by a 3rd party, in order to keep our documents accurate. + +Published versions of the specification are in the `versions/` folder. +The under-development versions of the specification are in the file `src/oas.md` on the appropriately-versioned branch. +For example, work on the next release for 3.2 is on `v3.2-dev` in the file `src/oas.md`. + +The [spec site](https://spec.openapis.org) is the source of truth for the OpenAPI specification as it contains all the citations and author credits (the markdown in this repository was previously the authoritative version until 2024). + +The OpenAPI project is almost entirely staffed by volunteers. +Please be patient with the people in this project, who all have other jobs and are active here because we believe this project has a positive impact in the world. + +### Active branches + +The current active specification releases are: + +| Version | Branch | Notes | +| ------- | ------ | ----- | +| 3.1.2 | `v3.1-dev` | active patch release line | +| 3.2.0 | `v3.2-dev` | minor release in development | +| 4.0.0 | [OAI/sig-moonwalk](https://github.com/OAI/sig-moonwalk) | [discussions only](https://github.com/OAI/sig-moonwalk/discussions) | + + +## How to contribute + +We welcome new contributors to the project whether you have changes to suggest, problems to report, or some feedback for us. +Please jump to the most relevant section from the list below: + +- Ask a question or offer feedback: use a [discussion](#discussions) +- Suggest a change or report a problem: open an [issue](#issues) +- Contribute a change to the repository: open a [pull request](#pull-requests) +- Or just [get in touch](#get-in-touch) + +## Discussions + +We use [discussions](https://github.com/OAI/OpenAPI-Specification/discussions?discussions_q=is%3Aopen) for anything that doesn't (yet) have a specific action associated with it. +Most ideas start as discussions. + +Please do come and start a discussion to: + +- ask questions +- make suggestions +- give feedback + +Anyone can start a discussion and you're very welcome to do so! Write a message and pick a relevant discussion category. + +### Discussion management + +Participation in discussions and especially answering of questions is encouraged (and appreciated) by everyone. + +Discussions are closed when: + +- the question has been answered. +- no further action or conversation would be useful. +- there has been no engagement for a while, or a previously popular thread has been inactive for an extended period. +- activity is now taking place elsewhere, such as in an issue. +- the discussion is out of scope for the project. + +## Issues + +Issues are for planned tasks, problems to solve, or requests for (specific) changes. +Most issues should have a clear outcome; something will be fixed, improved or otherwise measurably different when the issue is complete. + +We use [discussions](#discussions) for ideas and early-stage suggestions. + +> [!NOTE] +> For larger or more extensive changes, we have a formal [proposal process](#propose-a-specification-change) to give more structure where it's needed. + +The best issues give a clear and concise explanation of the problem at hand, and ideally some examples of what the problem is. +Suggested solutions are also welcome, but it is very important that the issue outlines the problem that is being solved as well as the solution. +Some issues may be a backlog of a task that needs to be done; other issues might be automatically created as part of the project processes. + +### Issue management + +We have some issue automation to close inactive issues and create/pin/archive the weekly meeting issues. +More information is in the [Appendix: Issue automation](#appendix-issue-automation) section. + +Everyone is encouraged to open and comment on issues in the project. +If you want to tag/assign/close something and you don't have enough permissions, add a comment and someone will help. + +Issues are managed by the [Triage](#triage), [Maintainers](#maintainers) and [TSC](#tsc) teams. +They may move issues to other repositories within the project as needed. + +In order to keep the issues list manageable and realistic for a relatively small group of volunteers, issues are proactively closed when it's not clear that they can be completed. +Issues may be closed when: + +- they have been inactive for a long time +- they are out of scope or no further constructive action can be taken +- they are complete (yay!) +- they are unclear and more details are not forthcoming +- as a group, there is agreement that no further action will be taken + +When issues are closed, a comment is added about why. +Closing issues is a reversible action, and it is always acceptable to comment and explain (politely) why an issue should not have been closed. + +### Labels + +We make extensive use of labels. +The main categories are: + +- [Housekeeping](https://github.com/OAI/OpenAPI-Specification/labels/Housekeeping) for meetings, project logistics, etc. +- [approved pr port](https://github.com/OAI/OpenAPI-Specification/labels/approved%20pr%20port) for pull requests that repeat a change from one version to another +- most other tags are used to group similar or related issues into topic areas; this list is ever-changing + +Labels related to [issue automation](#appendix-issue-automation) + +- [Needs attention](https://github.com/OAI/OpenAPI-Specification/labels/Needs%20attention) automated tag when an issue is updated +- [Needs author feedback](https://github.com/OAI/OpenAPI-Specification/labels/Needs%20author%20feedback) used to indicate that more information is needed from the issue creator +- [No recent activity](https://github.com/OAI/OpenAPI-Specification/labels/No%20recent%20activity) if no information is received, the issue is marked for closure (automatic after 30 days) + +### Milestones + +We use milestones in GitHub to plan what should be included in future releases. +Issues and pull requests should both be added to the earliest milestone we expect they will be released in. +Any changes that aren't ready in time for release should be moved to the next milestone or untagged. + +The milestones and items assigned to them are under constant review and subject to change. + +### Projects + +The OpenAPI Initiative uses GitHub Projects to manage work _outside_ of the specification development process. There are currently two active projects: + +* [Contributor Guidance](https://github.com/orgs/OAI/projects/5/views/1) +* [Automation & Infrastructure](https://github.com/orgs/OAI/projects/4/views/1) + +## Pull requests + +> [!NOTE] +> Since the 3.0.4 and 3.1.1 releases (October 2024), the OAS is developed in the `src/oas.md` file. +> Check the [Appendix: Branch Strategy](#appendix-branch-strategy) for more information about the updated branching strategy. + +Changes to the next version of the specification are welcome and can be proposed by anyone. + +For large changes that will need discussion, please use the [Proposal process](#propose-a-specification-change). +For other changes, we recommend [opening an issue](#issues) first, so that you can get some feedback and any extra input you need before spending a lot of time on something. + +Schema changes are made on the same branch, but can be released independently. +When making a specification change for a new minor or major release that has a schema impact, including the schema change in the PR is preferred. +Patch releases cannot contain changes that _require_ a schema update. + +### Use a fork + +All work **MUST be done on a fork** and be submitted as a pull request. + +### Target the earliest active `*-dev` branch + +Branch from and submit pull requests to the a branch from the _earliest relevant and [active](#active-branches)_ `vX.Y-dev` branch. +For example, if a change applies to both 3.1 and 3.2, the PR would go to the `v3.1-dev` branch, which will be merged up to `v3.2-dev` before the next 3.2 release. +All changes to the specification must conform to the [style guide](./style-guide.md). + +Both specification and schema changes follow this approach. + +For changes to repository files that affect all versions, use the `main` branch. +This might apply to, for example, Markdown files, automation, and scripts. + +For all pull requests, if they should not be merged yet for any reason (they depend on something else, you would like feedback from a specific reviewer), mark them as draft and they will not be merged while in that state. +Draft pull requests can still be reviewed while in draft state. + +### Preview specification HTML locally + +> [!NOTE] +> `npm run build-src` calls bash scripts. Use [Git Bash](https://gitforwindows.org/) on Windows, or use the Windows Subsystem for Linux (WSL). + +The markdown source files are converted to HTML before publishing. +To do this locally, please + +1. Install [Node.js](https://nodejs.org/) +2. Check out this repo, go to the repo root, and switch to a development branch +3. Execute `npm install` (once, repeat after merging upstream changes) +4. Execute `npm run build-src` after changing `src/oas.md` (this first executes `npm run validate-markdown`, which can also be run separately) +5. Open output file `deploy-preview/oas.html` with a browser and check your changes + +Please make sure the markdown validates and builds using the above steps before creating a pull request or marking a draft pull request as ready for review. + +## Reviewers + +> [!NOTE] +> See also the detailed team outlines in the [roles section](#roles). + +All pull requests must be reviewed and approved by one member of the TSC or Maintainers teams. +Reviews from other contributors are always welcome. + +Additionally, all pull requests that change the specification file `src/oas.md` must be approved by two TSC members. + +Reviews requesting changes should have their changes addressed regardless of how many other approvers there are. + +## Publishing + +### Specification Versions + +The specification versions are published to the [spec site](https://spec.openapis.org) by creating an `vX.Y.Z-rel` branch where `src/oas.md` is renamed to the appropriate `versions/X.Y.Z.md` file and then merged to `main`. +This renaming on the `vX.Y.Z-rel` branch preserves the commit history for the published file on `main` when using `git log --follow` (as is the case for all older published files). + +The steps for creating a `vX.Y.Z-rel` branch are: + +1. Update `EDITORS.md` on `main` +2. Merge `main` into `dev` and `dev` into `vX.Y-dev` via PRs + - sync PRs are automatically created by workflows `sync-main-to-dev` and `sync-dev-to-vX.Y-dev` +3. Prepare spec files in `vX.Y-dev` + - `npm run format-markdown` + - `npm run build-src` + - open `deploy-preview/oas.html` in browser and verify correct formatting + - adjust and repeat until done + - merge changes to `src/oas.md` back into `vX.Y-dev` via PR +4. Create `vX.Y.Z-rel` from `vX.Y-dev` and adjust it + - move `src/oas.md` to `versions/X.Y.Z.md` + - copy `EDITORS.md` to `versions/X.Y.Z-editors.md` + - delete `src/schemas` + - delete `tests/schema` + - bash script `scripts/adjust-release-branch.sh` performs these steps +5. Merge `vX.Y.Z-rel` into `main` via PR + - this PR should only add files `versions/X.Y.Z.md` and `versions/X.Y.Z-editors.md` + +The HTML renderings of the specification versions are generated from the `versions` directory on `main` by manually triggering the [`respec` workflow](https://github.com/OAI/OpenAPI-Specification/blob/main/.github/workflows/respec.yaml), which generates a pull request for publishing the HTML renderings to the [spec site](https://spec.openapis.org). + +### Schema Iterations + +The schema iterations are published independently from the specification releases [in the schema section on the spec site](https://spec.openapis.org/#openapi-specification-schemas). +Schemas are updated in and directly published from the `vX.Y-dev` branches. + +As part of the publishing process, the YAML source files are converted to JSON, renamed to the relevant last-changed dates, and `WORK-IN-PROGRESS` placeholders are replaced with these dates as appropriate. This is usually done by the `schema-publish` workflow which detects changes on each `vX.Y-dev` branch, which generates a pull request for publishing the new schema iterations to the [spec site](https://spec.openapis.org). The workflow can also be run manually if required. + +## Release Process and Scope + +This section relates to the 3.x versions only. + +### Minor Releases + +Our roadmap for 3.x releases is community-driven, meaning the specification is open for proposed additions by anyone (see [Propose a Specification Change](#propose-a-specification-change)), in addition to the issues already on the project backlog. + +Changes in minor releases (such as 3.2, 3.3) meet the following criteria: + +* Are **backwards-compatible** and be reasonably easy to implement in tooling that already supports the previous minor version. + For example, new optional fields can be added. +* Drive quality-of-life improvements to support how OpenAPI is used by practitioners, so that OpenAPI evolves to continue to meet user needs. + For example, adding fields to support changes in other standards, or adopting common `x-*` extension fields into the specification. +* Bring the future closer by making changes that are in line with future 3.x releases and the planned OpenAPI 4.x (Moonwalk) specification as the details of that become available. +* Make the specification document clearer or easier to understand. + +A minor release is due when there are some meaningful features (including one or a small number of headline features). + +### Patch Releases + +Patch releases reflect a constant quest for improving the active minor versions of OpenAPI. +Since we do not edit specification documents after publication, even the smallest change has to be in a new release. + +Changes in patch releases meet the following criteria: + +* Editorial changes such as spelling or formatting fixes, including link updates. +* Clarifications or additions that do not change the meaning of the specification. + +Patch releases are created as often as there are changes to the specification worth releasing. + +### Release Process + +A release requires a vote on the specification at a particular version and the associated release notes by TSC members within the voting period. +Major or minor release voting periods will be announced in the Slack channel and noted on the calendar at least 6 days in advance. +During this time, TSC members who have not yet voted must note their approval by leaving a comment on the GitHub pull request proposing the release; release notes should be included with the description. +TSC members are responsible for coordinating the information about the release to the outreach team as appropriate. + +* Patch-level releases require majority approval by TSC members. (Max voting period 3 days) + +* Minor: requires approval by 66% of TSC members. (Max voting period 7 days) + +* Major: requires approval by 66% of TSC members. (Max voting period 14 days) + +During the voting period, further changes should not be made to the specification being considered. + +Once the threshold of approvals is met, the release can be performed by any TSC member. + +## Propose a Specification Change + +As an organisation, we're open to changes, and these can be proposed by anyone. +The specification is very widely adopted, and there is an appropriately high bar for wide appeal and due scrutiny as a result. +We do not accept changes lightly (but we will consider any that we can). + +Small changes are welcome as pull requests. + +Bigger changes require a more formal process. + +1. Start a [discussion](https://github.com/OAI/OpenAPI-Specification/discussions) of type "Enhancements". + The discussion entry must include some use cases, your proposed solution and the alternatives you have considered. + If there is engagement and support for the proposal over time, then it can be considered as a candidate to move to the next stage. + +2. It really helps to see the proposed change in action. + Start using it as a `x-*` extension if that's appropriate, or try to bring other evidence of your proposed solution being adopted. + +3. If you are adding support for something from another specification (such as OAuth), please point to implementations of that + specification so that we can understand how, and to what degree, it is being used. + +4. If the suggested change has good support, you will be asked to create a formal proposal. + Use the [template in the proposals directory](https://github.com/OAI/OpenAPI-Specification/tree/main/proposals), copy it to a new file, and complete it. + Once you the document is ready, open a pull request on the main branch. + +5. The proposal will be more closely reviewed and commented on or amended until it is either rejected or accepted. + At that point, the proposal is merged into the `main` branch and a pull request is opened to add the feature to the appropriate `dev` version of the specification. + +Questions are welcome on the process at any time. Use the discussions feature or find us in Slack. + +## Roles + +The OpenAPI project has some key roles that are played by multiple people. + +### TSC + +The Technical Steering Committee are listed in the [MAINTAINERS file](./MAINTAINERS.md). +They are the maintainers of the OpenAPI Specification itself and every other aspect of the project operation and direction. +TSC members can review changes to all parts of the repository and make decisions about the project. + +### Maintainers + +The maintainers have write access to the repository and play a key role in the project. +They review pull requests to non-specification parts of the repository, and take on other strategic tasks around project planning and maintenance. + +### Triage + +The triage team are active OpenAPI members who help with discussion and issue management. +They respond to new issues and discussions, direct people to our existing resources or raise conversations to a wider audience. +The triage team keeps an eye on the backlog and closes issues and discussions that are no longer active or needed. + +## Get in touch + +To get in touch with other people on the project, ask questions, or anything else: + +- Find us [on the OpenAPI Slack](https://communityinviter.com/apps/open-api/openapi). +- Start a [GitHub Discussion](https://github.com/OAI/OpenAPI-Specification/discussions/). +- Join one of our weekly meetings by checking the [issues list for an upcoming meetings](https://github.com/OAI/OpenAPI-Specification/issues?q=is%3Aissue%20state%3Aopen%20label%3AHousekeeping). + +## Appendix: Branch strategy + +For information on the branch and release strategy for OAS 3.0.4 and 3.1.1 and earlier, see the comments in [issue #3677](https://github.com/OAI/OpenAPI-Specification/issues/3677). + +### Branch roles + +* `main` is used to publish finished work and hold the authoritative versions of general documentation such as this document, which can be merged out to other branches as needed. The `src` tree is _**not**_ present on `main`. +* `dev` is the primary branch for working with the `src` tree. Development infrastructure that is not needed on `main` is maintained here, and can be merged out to other non-`main` branches as needed. + Changes on `main` are automatically included in a pull request to `dev` (see the (section on [branch sync](#branch-sync-automation)). +* `vX.Y-dev` is the minor release line development branch for X.Y, including both the initial X.Y.0 minor version and all subsequent X.Y.Z patch versions. All PRs are made to oldest active `vX.Y-dev` branch to which the change is relevant, and then merged forward as shown in the diagram further down in this document. +* `vX.Y.Z-rel` is the release branch for an X.Y.Z release (including when Z == 0). It exists primarily for `git mv`-ing `src/oas.md` to the appropriate `versions/X.Y.Z.md` location before merging back to `main`, and can also be used for any emergency post-release fixes that come up, such as when a 3rd party changes URLs in a way that breaks published links. + +### Branching and merging (3.1.2, 3.2.0, and later) + +Upon release: + +* Pre-release steps: + * The most recent _published_ patch release from the previous line is merged up to `vX.Y-dev`, if relevant + * If doing simultaneous releases on multiple lines, do them from the oldest to newest line + * For example, if releasing 3.1.3 and 3.2.0: + * release 3.1.3 first + * release 3.2.0 second +* Release branching and merging: + * branch `vX.Y.Z-rel` from `vX.Y-dev` (same commit that was merged to `dev` if relevant) + * After renaming `src/oas.md` to `versions/X.Y.Z.md` and [other adjustments](#specification-versions), merge `vX.Y.Z-rel` to `main` +* Publishing to the [spec site](https://spec.openapis.org) is triggered by the merge to `main` +* Post-release steps: + * If this was a major or minor release (Z == 0), branch `vX.Y+1-dev` from `vX.Y-dev` + +_Release lines are grouped by color, although the colors of `dev` and `main` are not significant as these diagrams are limited to only 8 colors._ + +```mermaid +--- +config: + themeVariables: + git0: "#5588bb" + git1: "#cc8899" + git2: "#eedd88" + git3: "#ccbb66" + git4: "#aa9944" + git5: "#887722" + git6: "#99ccff" + git7: "#77aadd" + gitBranchLabel1: "#000000" + gitBranchLabel2: "#000000" + gitBranchLabel3: "#000000" + gitBranchLabel4: "#000000" + gitBranchLabel5: "#ffffff" + gitBranchLabel6: "#000000" + gitBranchLabel7: "#000000" +--- +gitGraph TB: + commit id:"merge 3.1.1.md to main" tag:"3.1.1" + branch dev order:1 + commit id:"rename 3.1.1.md to src/oas.md" + branch v3.1-dev order:2 + commit id:"update version in src/oas.md to 3.1.2" + checkout dev + branch v3.2-dev order:6 + commit id:"update version in src/oas.md to 3.2.0" + commit id:"some 3.2.0 work" + checkout v3.1-dev + commit id:"a 3.1.x fix" + checkout v3.2-dev + merge v3.1-dev id:"merge 3.1.2 fixes" + checkout v3.1-dev + branch v3.1.2-rel order:3 + commit id:"rename src/oas.md to versions/3.1.2.md" + + checkout main + merge v3.1.2-rel tag:"3.1.2" + checkout dev + merge main id:"auto-sync from main" + checkout v3.1-dev + merge dev id:"auto-sync from dev" + checkout v3.2-dev + merge dev id:"auto-sync from dev " + + commit id:"more 3.2.0 work" + checkout v3.1-dev + commit id:"update version in src/oas.md to 3.1.3" + commit id:"another 3.1.x fix" + checkout v3.2-dev + commit id:"still more 3.2.0 work" + merge v3.1-dev id:"merge 3.1.3 fixes before releasing" + + checkout v3.1-dev + branch v3.1.3-rel order:4 + commit id:"rename src/oas.md to versions/3.1.3.md" + checkout v3.2-dev + branch v3.2.0-rel order:7 + commit id:"rename src/oas.md to versions/3.2.0.md" + + checkout main + merge v3.1.3-rel tag:"3.1.3" + checkout dev + merge main id:" auto-sync from main" + checkout v3.1-dev + merge dev id:" auto-sync from dev" + checkout v3.2-dev + merge dev id:" auto-sync from dev " + + checkout main + merge v3.2.0-rel tag:"3.2.0" + checkout dev + merge main id:" auto-sync from main" + checkout v3.1-dev + merge dev id:" auto-sync from dev" + checkout v3.2-dev + merge dev id:" auto-sync from dev " + + checkout v3.2-dev + branch v3.3-dev order:9 + checkout v3.1-dev + commit id:"update version in src/oas.md to 3.1.4" + checkout v3.2-dev + commit id:"update version in src/oas.md to 3.2.1" + checkout v3.3-dev + commit id:"update version in src/oas.md to 3.3.0" + + checkout v3.1-dev + commit id:"a 3.1.4 fix" + checkout v3.2-dev + commit id:"a 3.2.1 fix" + merge v3.1-dev id:"merge 3.1.4 fixes before releasing" + checkout v3.3-dev + merge v3.2-dev id:"merge 3.1.4 / 3.2.1 fixes" + + checkout v3.1-dev + branch v3.1.4-rel order:5 + commit id:"rename src/oas.md to versions/3.1.4.md" + checkout v3.2-dev + branch v3.2.1-rel order:8 + commit id:"rename src/oas.md to versions/3.2.1.md" + + checkout main + merge v3.1.4-rel tag:"3.1.4" + checkout dev + merge main id:" auto-sync from main" + checkout v3.1-dev + merge dev id:" auto-sync from dev" + checkout v3.2-dev + merge dev id:" auto-sync from dev " + checkout v3.3-dev + merge dev id:" auto-sync from dev " + + checkout main + merge v3.2.1-rel tag:"3.2.1" + checkout dev + merge main id:" auto-sync from main" + checkout v3.1-dev + merge dev id:" auto-sync from dev" + checkout v3.2-dev + merge dev id:" auto-sync from dev " + checkout v3.3-dev + merge dev id:" auto-sync from dev " + + checkout v3.2-dev + commit id:"update version in src/oas.md to 3.2.2" + checkout v3.3-dev + commit id:"3.3 work" +``` + +### Branch sync automation + +To keep changes in sync, we have some GitHub actions that open pull requests to take changes from `main` onto the `dev` branch, and from `dev` to each active version branch. + +- `sync-main-to-dev` opens a pull request with all the changes from the `main` branch that aren't yet included on `dev`. +- `sync-dev-to-vX.Y-dev` opens pull requests with all the changes from `dev` that aren't yet included on the corresponding `vX.Y-dev` branch. + +These need a single approval from either maintainers or TSC and can be merged. +The aim is to bring build script and repository documentation changes to the other branches. +Published versions of the specifications and schemas will also move across branches with this approach. + +## Appendix: Issue Automation + +### Automated closure of issues Process + +In an effort to keep the list of issues up to date and easier to navigate through, issues get closed automatically when they become inactive. + +This process makes use of the following labels: + +* `Needs author feedback`: the issue has been replied to by the triage team and is awaiting a follow up from the issue's author. This label needs to be added manually by people doing triage/experts whenever they reply. It's removed automatically by the workflow. +* `No recent activity`: the issue hasn't received a reply from its author within the last 10 days since `Needs author feedback` was added and will be closed within 28 days if the author doesn't follow up. This label is added/removed automatically by the workflow. +* `Needs attention`: The issue's author has replied since the `Needs author feedback` label was set and the triage team will reply as soon as possible. This label needs to be removed manually by people doing triage/experts whenever they reply. It's added automatically by the workflow. + +### Automated TDC agenda issues Process + +An issue is opened every week, 7 days in advance, for the Technical Developer Community (TDC), it provides the information to connect the meeting, and serves as a placeholder to build the agenda for the meeting. Anyone is welcome to attend the meeting, or to add items to the agenda as long as they plan on attending to present the item. These issues are also automatically pinned for visibility and labeled with "Housekeeping". + +Ten (10) days after the meeting date is passed (date in the title of the issue), it gets closed and unpinned automatically. + diff --git a/DEVELOPMENT.md b/DEVELOPMENT.md deleted file mode 100644 index b975f55b98..0000000000 --- a/DEVELOPMENT.md +++ /dev/null @@ -1,56 +0,0 @@ -## Development Guidelines - -This document intends to establish guidelines which build a transparent, open mechanism for deciding how to evolve the OpenAPI Specification. The Open API Technical Steering Committee (TSC) will initially follow these processes when merging changes from external contributors or from the TSC itself. This guideline document will be adjusted as practicality dictates. - -## OAI Specification Driving factors - -The OpenAPI Specification should be use-case driven. We can specify support for hypothetical use cases as we see fit, but specifications should be backed by realistic scenarios. - -## Specification Change Criteria - -The specification _will change_ from the original 2.0 version. We should typically make changes when any of the following criteria are met: - - - Clarity. The current "way" something is done doesn't make sense, is complicated, or not clear. - - Consistency. A portion of the specification is not consistent with the rest, or with the industry standard terminology. - - Necessary functionality. We are missing functionality because of a certain design of the specification. - - Forward-looking designs. As usage of APIs evolves to new protocols, formats, and patterns, we should always consider what the next important functionality should be. - - Impact. A change will provide impact on a large number of use cases. We should not be forced to accommodate every use case. We should strive to make the _common_ and _important_ use cases both well supported and common in the definition of the OAI Spec. We cannot be edge-case driven. - - -## Tracking Process - - - Use GitHub for all spec designs, use cases, and so on. - - As with 2.0, the **human readable** document is the source of truth. If using a JSON Schema again to document the spec, it is secondary to the human documentation. The documentation should live in a *.md file, in parallel to the 2.0 document (versions/3.0.0.md for example). - - At any given time, there would be _at most_ 4 work branches. The branches would exist if work has started on them. Assuming a current version of 3.0.0: - - `master` - Current stable version. No PRs would be accepted directly to modify the specification. PRs against supporting files can be accepted. - - `v3.0.1` - The next PATCH version of the specification. This would include non-breaking changes such as typo fixes, document fixes, wording clarifications. - - `v3.1.0` - The next MINOR version. - - `v4.0.0` - The next MAJOR version. - - The `master` branch shall remain the current, released OpenAPI Specification. We will describe and link the work branch(es) on the **default** README.md on master. - - Examples of how something is described _currently_ vs. the proposed solution should accompany any change proposal. - - New features should be done in feature branches/forks which, upon approval, are merged into the proper work branch. - - Use labels for the workflow of specification changes. Examples of labels are `proposed`, `needs migration review`, `needs tooling review`, `needs documentation`, `rejected`, and `needs approval`. These labels must be assigned by project committers. - - An issue will be opened for each feature change. Embedded in the issue, or ideally linked in a file via pull-request (PR), a document about use cases should be supplied with the change. - - A PR will be used to describe the _proposed_ solution, and linked to the original issue. - - Not all committers will contribute to every single proposed change. There may be many open proposals at once, and multiple efforts may happen in parallel. - - When the a work branch is ready and approved, the branch will be merged to master. - -## Approving Changes - -For each change in the specification we should _always_ consider the following: - - - Migration. Is this a construct that has a path from the existing 2.0 specification? If so, how complicated is it to migrate to the proposed change? - - Tooling. Strive to support code generation, software interfaces, and spec generation techniques. Some features may be impossible to support in different frameworks/languages. These should be documented and considered during the change approval process. - - Visualization. Can the specification change be graphically visualized somehow in a UI or other interface? - -Spec changes should be approved by a majority of the committers. Approval can be given by commenting on the issue itself, for example, "Approved by @webron". After voting criteria is met, any committer can merge the PR. (**TODO**: we will want to formalize what voting criteria actually is). - -No change should be approved until there is documentation for it, supplied in an accompanying PR. - -## Transparency - -We should always be as transparent as possible. Sometimes there will be discussions that use customer names, sensitive use cases, and so on. These must be anonymized, discussed in a private repository, or conducted offline. - - - Asynchronous discussions should live in the GitHub issues for this project. - - Realtime discussions should be in a public chat such as IRC or Slack. - diff --git a/EDITORS.md b/EDITORS.md new file mode 100644 index 0000000000..d55306b1f8 --- /dev/null +++ b/EDITORS.md @@ -0,0 +1,20 @@ +# OpenAPI Specification Editors + +## Active + +* Darrel Miller [@darrelmiller](https://github.com/darrelmiller) +* Henry Andrews [@handrews](https://github.com/handrews) +* Jeremy Whitlock [@whitlockjc](https://github.com/whitlockjc) +* Lorna Mitchell [@lornajane](https://github.com/lornajane) +* Marsh Gardiner [@earth2marsh](https://github.com/earth2marsh) +* Miguel Quintero [@miqui](https://github.com/miqui) +* Mike Kistler [@mikekistler](https://github.com/mikekistler) +* Ralf Handl [@ralfhandl](https://github.com/ralfhandl) +* Ron Ratovsky [@webron](https://github.com/webron) + +## Emeritus + +* Mike Ralphson [@MikeRalphson](https://github.com/MikeRalphson) +* Uri Sarid [@usarid](https://github.com/usarid) +* Jason Harmon [@jharmn](https://github.com/jharmn) +* Tony Tam [@fehguy](https://github.com/fehguy) diff --git a/GOVERNANCE.md b/GOVERNANCE.md index e9eda78d71..2fe0e5f54e 100644 --- a/GOVERNANCE.md +++ b/GOVERNANCE.md @@ -1,30 +1,37 @@ # Governance -The OpenAPI Specification is a project of the Open API Initiative (OAI), under the auspices of the Linux Foundation. For governance of the OAI, review the [OAI's charter](https://www.openapis.org/participate/how-to-contribute/governance). +The OpenAPI Specification is a project of the OpenAPI Initiative (OAI), under the auspices of the Linux Foundation. For governance of the OAI, review the [OAI's charter](https://www.openapis.org/participate/how-to-contribute/governance). -# Processes and procedures of the Technical Steering Committee (TSC) +## Processes and procedures of the Technical Steering Committee (TSC) The TSC is a self-organizing sub-group of the OAI. Herein are its principles and guidelines. -## 1. The establishment of roles and the responsibilities for each role +### 1. The establishment of roles and the responsibilities for each role Roles: * [Liaison](https://www.merriam-webster.com/dictionary/liaison) — Elected by TSC members in a plurality vote (oral count). Liaison represents the TSC to the OAI's Business Governing Board (BGB) at board meetings (though this itself does not confer voting rights) and is the public facing mouthpiece of the TSC. -* [Maintainer](https://www.merriam-webster.com/dictionary/maintainer) — all and only members of the TSC are maintainers, and are responsible for approving proposed changes to the specification. If membership drops below 3, work is suspended until the BGB can re-establish the minimum. To maintain agility, the TSC should be capped at a maximum 9 members, though that number can be reconsidered by the TSC in the future. Past members will be noted as emeritus status once they are no longer members. +* [Maintainer](https://www.merriam-webster.com/dictionary/maintainer) — all and only members of the TSC are maintainers, and are responsible for approving proposed changes to the specification. If membership drops below 3, work is suspended until the BGB can re-establish the minimum. To maintain agility, the TSC should be capped at a maximum 9 members, though that number can be reconsidered by the TSC in the future. Past members will be noted as emeritus status once they are no longer members. + +* [Community Manager](https://en.wikipedia.org/wiki/Online_community_manager) — responsible for onboarding of new contributors, dealing with antisocial behaviour before it becomes a code of conduct violation, and managing the issue triage team. * [Rick](https://www.youtube.com/watch?v=dQw4w9WgXcQ) — Responsible for not giving up or letting down. Requires plurality vote of TSC members. -## 2. Adding members to the TSC +### 2. Adding members to the TSC -A call-for-nominations period may be agreed upon by the TSC voting members and announced in a timely manner through [@OpenApiSpec](https://twitter.com/OpenApiSpec) on Twitter, assuming the TSC membership is not already at its maximum. A candidate may be nominated through a motion by a voting TSC member in a closed TSC meeting. A nominee must not receive opposition votes of more than 25% of the TSC voting membership via a confidential vote held electronically within a week following the nomination meeting. Approved nominees become provisional members and are expected to comport themselves as full members of the TSC during the provisional period of 4-6 weeks (to be determined at start of each nominating period), though nominees have no voting rights. The provisional period is concluded by a second, confidential vote similar to the nomination period's vote. At most there are four voting periods per year (no more than one every three months), with a minimum of one per year. +A call-for-nominations period may be agreed upon by the TSC voting members and announced in a timely manner on a weekly TDC call (and documented on the agenda issue), assuming the TSC membership is not already at its maximum. +A candidate may be nominated through a motion by a voting TSC member in a closed TSC meeting. +A nominee must not receive opposition votes of more than 25% of the TSC voting membership via a confidential vote held electronically within a week following the nomination meeting. +Approved nominees become provisional members and are expected to comport themselves as full members of the TSC during the provisional period of 6 months. +The provisional period is concluded by a second, confidential vote similar to the nomination period's vote, after which newly confirmed members gain their voting rights. +At most there are four voting periods per year (no more than one every three months), with a minimum of one per year. -## 3. Removal of membership from the TSC +### 3. Removal of membership from the TSC -In dire situations, it may be necessary to remove a TSC member, such as behavior that violates the code of conduct (NB: whether non-participation merits removal is a decision left to the TSC voting members). 75% vote (confidential, electronic) of the other TSC members is required to remove a member. Otherwise, TSC members are removed when they renounce their position by informing the Liaison of their effective resignation date. +Occasionally it may be necessary to remove a TSC member, such as behavior that violates the code of conduct or prolonged absenteeism. A 66% vote (confidential, electronic) of the other TSC members is required to remove a member. Otherwise, TSC members are removed when they renounce their position by informing the TSC of their effective resignation date via email. -## 4. Criteria for decisions +### 4. Criteria for decisions The group will strive to achieve all decisions via unopposed consensus. When not possible, unresolved conflicts will be raised to the OAI's Technical Oversight Board (TOB). diff --git a/IMPLEMENTATIONS.md b/IMPLEMENTATIONS.md index 64a0179cb0..859c5d7df7 100644 --- a/IMPLEMENTATIONS.md +++ b/IMPLEMENTATIONS.md @@ -1,62 +1,9 @@ -### Implementations +# Implementations -Below is a list of known tooling that implements the 3.0.0 specification. While support for the 3.0.0 specification matures, refer to the details of projects listed below for any notes about stability and roadmap. The process to improve the 3.x specification includes feedback from end-users and tooling creators. We strongly encourage draft tooling be made available for early users of OAS drafts. +The list of implementations formerly in this file is no-longer maintained here. -These tools are not necessarily endorsed by the OAI. +You may find a more comprehensive list at -#### Low-Level tooling - -| Title | Project Link | Language |Description | -|----------------|--------------|----------|---------------------| -| swagger-parser | [GitHub/swagger-api](https://github.com/swagger-api/swagger-parser/tree/feature/3.0.0-rc0) | Java | Swagger 1.0, 1.1, 1.2, 2.0 to Open API Specification converter | -| swagger-models | [GitHub/swagger-api](https://github.com/swagger-api/swagger-core/tree/feature/3.0.0-rc0/modules/swagger-models) | Java | Open API 3.0 Java Pojos | -| KaiZen OpenAPI Parser | [GitHub/RepreZen/KaiZen-OpenAPI-Parser](https://github.com/RepreZen/KaiZen-OpenAPI-Parser) | Java | High-performance Parser, Validator, and Java Object Model for OpenAPI 3.x | -| openapi3-ts | [GitHub/metadevpro/openapi3-ts](https://github.com/metadevpro/openapi3-ts) | TypeScript | TS Model & utils for OpenAPI 3.0.x contracts | -| swagger2openapi | [GitHub/mermade/swagger2openapi](https://github.com/mermade/swagger2openapi) | Node.js | An OpenAPI / Swagger 2.0 to OpenAPI 3.0.x converter and validator | -| Microsoft.OpenApi.net | [GitHub/microsoft/OpenApi.net](https://github.com/microsoft/openapi.net/) | dotnet | C# based parser with definition validation and migration support from V2 | -| odata-openapi | [GitHub/oasis-tcs/odata-openapi](https://github.com/oasis-tcs/odata-openapi) | XSLT | OData 4.0 to OpenAPI 3.0.0 converter | -| openapi3_parser | [GitHub/kevindew/openapi3_parser](https://github.com/kevindew/openapi3_parser) | Ruby | A Ruby implementation of parser and validator for the OpenAPI 3 Specification | -| oas_parser | [GitHub/Nexmo/oas_parser](https://github.com/Nexmo/oas_parser) | Ruby | An open source OpenAPI Spec 3 Definition Parser writen in Ruby | - - -#### Editors - -| Title | Project Link | Language |Description | -|----------------|--------------|----------|---------------------| -| Apicurio Studio | [GitHub/Apicurio/apicurio-studio](https://github.com/Apicurio/apicurio-studio) | Java/Typescript | Web-Based **visual designer** for OpenAPI 2.0 and 3.0.0. | -| KaiZen OpenAPI Editor | [GitHub/RepreZen/KaiZen-OpenAPI-Editor](https://github.com/RepreZen/KaiZen-OpenAPI-Editor) | Java | Eclipse Editor for OpenAPI 2.0 and 3.0 | -| RepreZen API Studio | [RepreZen.com/OpenAPI](https://www.reprezen.com/OpenAPI) | Java | Commercial desktop IDE for API design, documentation & development | -| OpenApi-gui | [GitHub/Mermade/openapi-gui](https://github.com/Mermade/openapi-gui) | Node.js | GUI / visual editor for creating and editing OpenApi / Swagger definitions | -| SwaggerHub | [swaggerhub.com](https://swaggerhub.com) | | API Design and Documentation Platform, Built For Teams -| swagger-editor | [GitHub/swagger-api](https://github.com/swagger-api/swagger-editor) | JavaScript | Web-Based editor for creating, editing, validating and testing OpenAPI\Swagger definitions | - -#### User Interfaces - -| Title | Project Link | Language |Description | -|----------------|--------------|----------|---------------------| -| openapi-viewer | [GitHub/koumoul/openapi-viewer](https://github.com/koumoul-dev/openapi-viewer) | Vue.js | Browse and test a REST API described with the OpenAPI 3.0 Specification. | -| swagger-ui | [GitHub/swagger-api](https://github.com/swagger-api/swagger-UI) | JavaScript | Web-Based interface for visualizing and testing OpenAPI\Swagger definitions | -| lincoln | [GitHub/temando/open-api-renderer](https://github.com/temando/open-api-renderer)| React.js| A React renderer for Open API v3 | -| WebSphere Liberty | [Download jar](https://developer.ibm.com/wasdev/downloads/) | JavaScript | Includes a native OpenAPI v3 UI which allows for customization of its banners and URL | -| Widdershins | [GitHub/Mermade/widdershins](https://github.com/Mermade/widdershins) | Node.js | Generate Slate/Shins markdown from OpenAPI 3.0.x | -| angular-swagger-ui | [GitHub/angular-swagger-ui](https://github.com/Orange-OpenSource/angular-swagger-ui) | AngularJS | An angularJS implementation of Swagger UI | - -#### Server Implementations -| Title | Project Link | Language |Description | -|----------------|--------------|----------|---------------------| -| Vert.x Web API Contract | [Github/vert-x3/vertx-web](http://vertx.io/docs/#web) | Java, Kotlin, JavaScript, Groovy, Ruby, Ceylon & Scala | Create an API endpoint with Vert.x 3 and OpenAPI 3 with automatic requests validation -| Fusio | [Github/apioo/fusio](https://github.com/apioo/fusio) | PHP, JavaScript | Build API endpoints based on OpenAPI 3 -| Modern | [Github/modern-project/modern-ruby](https://github.com/modern-project/modern-ruby) | Ruby | OpenAPI 3-based Rack framework with automatic OAS generation and requests/response validation - -#### Code Generators - -| Title | Project Link | Language |Description | -|----------------|--------------|----------|---------------------| -| baucis-openapi3 | [Github/metadevpro/baucis-openapi3](https://github.com/metadevpro/baucis-openapi3) | Node.js | [Baucis.js](https://github.com/wprl/baucis) plugin for generating OpenAPI 3.0 compliant API contracts. | -| Google Gnostic | [GitHub/googleapis/gnostic](https://github.com/googleapis/gnostic) | Go | Compile OpenAPI descriptions into equivalent Protocol Buffer representations. | -| serverless-openapi-documentation | [GitHub/temando/serverless-openapi-documentation](https://github.com/temando/serverless-openapi-documentation) | Typescript | Serverless 1.0 plugin to generate OpenAPI V3 documentation from serverless configuration | -| zero-rails_openapi | [GitHub/zhandao/zero-rails_openapi](https://github.com/zhandao/zero-rails_openapi) | Ruby | Provide concise DSL for generating the OpenAPI Specification 3 documentation file for Rails application | -| slush-vertx | [Github/pmlopes/slush-vertx](https://github.com/pmlopes/slush-vertx) | Java, Kotlin & Groovy | Generate server skeleton for [Vert.x Web API Contract](http://vertx.io/docs/#web) and API Client based on [Vert.x 3 Web Client](http://vertx.io/docs/#web) -| WebSphere Liberty | [Download jar](https://developer.ibm.com/wasdev/downloads/) | Java EE | Generates OpenAPI v3 documentation from Java EE applications | -| swagger-node-codegen | [Github/fmvilas/swagger-node-codegen](https://github.com/fmvilas/swagger-node-codegen) | Node.js | Generates a Node.js/express server, but also has a template engine for creating any templates needed. | +Instructions on listing your projects are contained in +These tools are not endorsed by the OAI. diff --git a/LICENSE b/LICENSE index 8d9ebfcb19..23b34fdff2 100644 --- a/LICENSE +++ b/LICENSE @@ -1,11 +1,201 @@ -Copyright 2017 The Linux Foundation + Apache License + Version 2.0, January 2004 + http://www.apache.org/licenses/ -Licensed under the Apache License, Version 2.0 (the "License"); -you may not use this file except in compliance with the License. -You may obtain a copy of the License at [apache.org/licenses/LICENSE-2.0](http://www.apache.org/licenses/LICENSE-2.0) + TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION -Unless required by applicable law or agreed to in writing, software -distributed under the License is distributed on an "AS IS" BASIS, -WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -See the License for the specific language governing permissions and -limitations under the License. + 1. Definitions. + + "License" shall mean the terms and conditions for use, reproduction, + and distribution as defined by Sections 1 through 9 of this document. + + "Licensor" shall mean the copyright owner or entity authorized by + the copyright owner that is granting the License. + + "Legal Entity" shall mean the union of the acting entity and all + other entities that control, are controlled by, or are under common + control with that entity. For the purposes of this definition, + "control" means (i) the power, direct or indirect, to cause the + direction or management of such entity, whether by contract or + otherwise, or (ii) ownership of fifty percent (50%) or more of the + outstanding shares, or (iii) beneficial ownership of such entity. + + "You" (or "Your") shall mean an individual or Legal Entity + exercising permissions granted by this License. + + "Source" form shall mean the preferred form for making modifications, + including but not limited to software source code, documentation + source, and configuration files. + + "Object" form shall mean any form resulting from mechanical + transformation or translation of a Source form, including but + not limited to compiled object code, generated documentation, + and conversions to other media types. + + "Work" shall mean the work of authorship, whether in Source or + Object form, made available under the License, as indicated by a + copyright notice that is included in or attached to the work + (an example is provided in the Appendix below). + + "Derivative Works" shall mean any work, whether in Source or Object + form, that is based on (or derived from) the Work and for which the + editorial revisions, annotations, elaborations, or other modifications + represent, as a whole, an original work of authorship. For the purposes + of this License, Derivative Works shall not include works that remain + separable from, or merely link (or bind by name) to the interfaces of, + the Work and Derivative Works thereof. + + "Contribution" shall mean any work of authorship, including + the original version of the Work and any modifications or additions + to that Work or Derivative Works thereof, that is intentionally + submitted to Licensor for inclusion in the Work by the copyright owner + or by an individual or Legal Entity authorized to submit on behalf of + the copyright owner. For the purposes of this definition, "submitted" + means any form of electronic, verbal, or written communication sent + to the Licensor or its representatives, including but not limited to + communication on electronic mailing lists, source code control systems, + and issue tracking systems that are managed by, or on behalf of, the + Licensor for the purpose of discussing and improving the Work, but + excluding communication that is conspicuously marked or otherwise + designated in writing by the copyright owner as "Not a Contribution." + + "Contributor" shall mean Licensor and any individual or Legal Entity + on behalf of whom a Contribution has been received by Licensor and + subsequently incorporated within the Work. + + 2. Grant of Copyright License. Subject to the terms and conditions of + this License, each Contributor hereby grants to You a perpetual, + worldwide, non-exclusive, no-charge, royalty-free, irrevocable + copyright license to reproduce, prepare Derivative Works of, + publicly display, publicly perform, sublicense, and distribute the + Work and such Derivative Works in Source or Object form. + + 3. Grant of Patent License. Subject to the terms and conditions of + this License, each Contributor hereby grants to You a perpetual, + worldwide, non-exclusive, no-charge, royalty-free, irrevocable + (except as stated in this section) patent license to make, have made, + use, offer to sell, sell, import, and otherwise transfer the Work, + where such license applies only to those patent claims licensable + by such Contributor that are necessarily infringed by their + Contribution(s) alone or by combination of their Contribution(s) + with the Work to which such Contribution(s) was submitted. If You + institute patent litigation against any entity (including a + cross-claim or counterclaim in a lawsuit) alleging that the Work + or a Contribution incorporated within the Work constitutes direct + or contributory patent infringement, then any patent licenses + granted to You under this License for that Work shall terminate + as of the date such litigation is filed. + + 4. Redistribution. You may reproduce and distribute copies of the + Work or Derivative Works thereof in any medium, with or without + modifications, and in Source or Object form, provided that You + meet the following conditions: + + (a) You must give any other recipients of the Work or + Derivative Works a copy of this License; and + + (b) You must cause any modified files to carry prominent notices + stating that You changed the files; and + + (c) You must retain, in the Source form of any Derivative Works + that You distribute, all copyright, patent, trademark, and + attribution notices from the Source form of the Work, + excluding those notices that do not pertain to any part of + the Derivative Works; and + + (d) If the Work includes a "NOTICE" text file as part of its + distribution, then any Derivative Works that You distribute must + include a readable copy of the attribution notices contained + within such NOTICE file, excluding those notices that do not + pertain to any part of the Derivative Works, in at least one + of the following places: within a NOTICE text file distributed + as part of the Derivative Works; within the Source form or + documentation, if provided along with the Derivative Works; or, + within a display generated by the Derivative Works, if and + wherever such third-party notices normally appear. The contents + of the NOTICE file are for informational purposes only and + do not modify the License. You may add Your own attribution + notices within Derivative Works that You distribute, alongside + or as an addendum to the NOTICE text from the Work, provided + that such additional attribution notices cannot be construed + as modifying the License. + + You may add Your own copyright statement to Your modifications and + may provide additional or different license terms and conditions + for use, reproduction, or distribution of Your modifications, or + for any such Derivative Works as a whole, provided Your use, + reproduction, and distribution of the Work otherwise complies with + the conditions stated in this License. + + 5. Submission of Contributions. Unless You explicitly state otherwise, + any Contribution intentionally submitted for inclusion in the Work + by You to the Licensor shall be under the terms and conditions of + this License, without any additional terms or conditions. + Notwithstanding the above, nothing herein shall supersede or modify + the terms of any separate license agreement you may have executed + with Licensor regarding such Contributions. + + 6. Trademarks. This License does not grant permission to use the trade + names, trademarks, service marks, or product names of the Licensor, + except as required for reasonable and customary use in describing the + origin of the Work and reproducing the content of the NOTICE file. + + 7. Disclaimer of Warranty. Unless required by applicable law or + agreed to in writing, Licensor provides the Work (and each + Contributor provides its Contributions) on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or + implied, including, without limitation, any warranties or conditions + of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A + PARTICULAR PURPOSE. You are solely responsible for determining the + appropriateness of using or redistributing the Work and assume any + risks associated with Your exercise of permissions under this License. + + 8. Limitation of Liability. In no event and under no legal theory, + whether in tort (including negligence), contract, or otherwise, + unless required by applicable law (such as deliberate and grossly + negligent acts) or agreed to in writing, shall any Contributor be + liable to You for damages, including any direct, indirect, special, + incidental, or consequential damages of any character arising as a + result of this License or out of the use or inability to use the + Work (including but not limited to damages for loss of goodwill, + work stoppage, computer failure or malfunction, or any and all + other commercial damages or losses), even if such Contributor + has been advised of the possibility of such damages. + + 9. Accepting Warranty or Additional Liability. While redistributing + the Work or Derivative Works thereof, You may choose to offer, + and charge a fee for, acceptance of support, warranty, indemnity, + or other liability obligations and/or rights consistent with this + License. However, in accepting such obligations, You may act only + on Your own behalf and on Your sole responsibility, not on behalf + of any other Contributor, and only if You agree to indemnify, + defend, and hold each Contributor harmless for any liability + incurred by, or claims asserted against, such Contributor by reason + of your accepting any such warranty or additional liability. + + END OF TERMS AND CONDITIONS + + APPENDIX: How to apply the Apache License to your work. + + To apply the Apache License to your work, attach the following + boilerplate notice, with the fields enclosed by brackets "{}" + replaced with your own identifying information. (Don't include + the brackets!) The text should be enclosed in the appropriate + comment syntax for the file format. We also recommend that a + file or class name and description of purpose be included on the + same "printed page" as the copyright notice for easier + identification within third-party archives. + + Copyright The Linux Foundation + + Licensed under the Apache License, Version 2.0 (the "License"); + you may not use this file except in compliance with the License. + You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. diff --git a/MAINTAINERS.md b/MAINTAINERS.md index 34421f2c62..1b32d59ff6 100644 --- a/MAINTAINERS.md +++ b/MAINTAINERS.md @@ -1,11 +1,19 @@ +# OpenAPI Initiative Technical Steering Committee Members + ## Active -* Darrel Miller [@darrelmiller](https://github.com/darrelmiller) + * Jeremy Whitlock [@whitlockjc](https://github.com/whitlockjc) * Marsh Gardiner [@earth2marsh](https://github.com/earth2marsh) -* Mike Ralphson [@MikeRalphson](https://github.com/MikeRalphson) * Ron Ratovsky [@webron](https://github.com/webron) -* Uri Sarid [@usarid](https://github.com/usarid) +* Lorna Mitchell [@lornajane](https://github.com/lornajane) +* Mike Kistler [@mikekistler](https://github.com/mikekistler) +* Miguel Quintero [@miqui](https://github.com/miqui) +* Ralf Handl [@ralfhandl](https://github.com/ralfhandl) ## Emeritus + +* Darrel Miller [@darrelmiller](https://github.com/darrelmiller) +* Mike Ralphson [@MikeRalphson](https://github.com/MikeRalphson) +* Uri Sarid [@usarid](https://github.com/usarid) * Jason Harmon [@jharmn](https://github.com/jharmn) * Tony Tam [@fehguy](https://github.com/fehguy) diff --git a/README.md b/README.md index c432ba4236..99aaa2348b 100644 --- a/README.md +++ b/README.md @@ -1,61 +1,54 @@ # The OpenAPI Specification -[![Build Status](https://travis-ci.org/OAI/OpenAPI-Specification.svg?branch=master)](https://travis-ci.org/OAI/OpenAPI-Specification) +![Build Status](https://github.com/OAI/OpenAPI-Specification/workflows/validate-markdown/badge.svg) [![Issue triagers](https://www.codetriage.com/oai/openapi-specification/badges/users.svg)](https://www.codetriage.com/oai/openapi-specification) + +![OpenAPI logo](https://avatars3.githubusercontent.com/u/16343502?v=3&s=200) -![](https://avatars3.githubusercontent.com/u/16343502?v=3&s=200) The OpenAPI Specification is a community-driven open specification within the [OpenAPI Initiative](https://www.openapis.org/), a Linux Foundation Collaborative Project. -The OpenAPI Specification (OAS) defines a standard, programming language-agnostic interface description for [REST APIs](https://en.wikipedia.org/wiki/Representational_state_transfer), which allows both humans and computers to discover and understand the capabilities of a service without requiring access to source code, additional documentation, or inspection of network traffic. When properly defined via OpenAPI, a consumer can understand and interact with the remote service with a minimal amount of implementation logic. Similar to what interface descriptions have done for lower-level programming, the OpenAPI Specification removes guesswork in calling a service. +The OpenAPI Specification (OAS) defines a standard, programming language-agnostic interface description for HTTP APIs. This allows both humans and computers to discover and understand the capabilities of a service without requiring access to source code, additional documentation, or inspection of network traffic. When properly defined via OpenAPI, a consumer can understand and interact with the remote service with a minimal amount of implementation logic. Similar to what interface descriptions have done for lower-level programming, the OpenAPI Specification removes guesswork in calling a service. -Use cases for machine-readable API definition documents include, but are not limited to: interactive documentation; code generation for documentation, clients, and servers; and automation of test cases. OpenAPI documents describe an API's services and are represented in either YAML or JSON formats. These documents may either be produced and served statically or be generated dynamically from an application. +Use cases for machine-readable API definition documents include, but are not limited to: interactive documentation; code generation for documentation, clients, and servers; and automation of test cases. OpenAPI documents describe API services and are represented in YAML or JSON formats. These documents may be produced and served statically or generated dynamically from an application. -The OpenAPI Specification does not require rewriting existing APIs. It does not require binding any software to a service — the service being described may not even be owned by the creator of its description. It does, however, require the capabilities of the service be described in the structure of the OpenAPI Specification. Not all services can be described by OpenAPI — this specification is not intended to cover every possible style of REST APIs. The OpenAPI Specification does not mandate a specific development process such as design-first or code-first. It does facilitate either technique by establishing clear interactions with a REST API. +The OpenAPI Specification does not require rewriting existing APIs. It does not require binding any software to a service – the described service may not even be owned by the creator of its description. It does, however, require that the service's capabilities be described in the structure of the OpenAPI Specification. Not all services can be described by OpenAPI – this specification is not intended to cover every possible style of HTTP APIs, but does include support for [REST APIs](https://en.wikipedia.org/wiki/Representational_state_transfer). The OpenAPI Specification does not mandate a specific development process such as design-first or code-first. It does facilitate either technique by establishing clear interactions with an HTTP API. This GitHub project is the starting point for OpenAPI. Here you will find the information you need about the OpenAPI Specification, simple examples of what it looks like, and some general information regarding the project. -## Current Version - 3.0.1 - -The current version of the OpenAPI specification is [OpenAPI Specification 3.0.1](versions/3.0.1.md). - -### Future Versions - -[3.0.2](https://github.com/OAI/OpenAPI-Specification/tree/v3.0.2-dev) - The next PATCH version. Patch-level fixes (typos, clarifications, etc.) should be submitted against this branch. +## Versions -### Previous Versions - -This repository also contains the [OpenAPI Specification 2.0](versions/2.0.md), which is identical to the Swagger 2.0 specification before it was renamed to "OpenAPI Specification", as well as the Swagger 1.2 and Swagger 2.0 specifications. - -Each folder in this repository, such as [examples](examples) and [schemas](schemas), should contain folders pertaining to the current and previous versions of the specification. +This repository contains [the Markdown sources](versions) for [all published OpenAPI Specification versions](https://spec.openapis.org/). For release notes and release candidate versions, refer to the [releases page](https://github.com/OAI/OpenAPI-Specification/releases). ## See It in Action -If you just want to see it work, check out the [list of current examples](examples/v3.0). +If you just want to see it work, check out the [list of current examples](https://learn.openapis.org/examples/). ## Tools and Libraries Looking to see how you can create your own OpenAPI definition, present it, or otherwise use it? Check out the growing -[list of 3.0 implementations](IMPLEMENTATIONS.md). +[list of implementations](IMPLEMENTATIONS.md). ## Participation -The current process for development of the OpenAPI Specification is described in -[Development Guidelines](DEVELOPMENT.md). -Development of the next version of the OpenAPI Specification is guided by the [Technical Steering Committee (TSC)](https://www.openapis.org/participate/how-to-contribute/governance#TDC). This group of committers bring their API expertise, incorporate feedback from the community, and expand the group of committers as appropriate. All development activity on the future specification will be performed as features and merged into this branch. Upon release of the future specification, this branch will be merged to master. +The current process for developing the OpenAPI Specification is described in +the [Contributing Guidelines](CONTRIBUTING.md). + +Developing the next version of the OpenAPI Specification is guided by the [Technical Steering Committee (TSC)](https://www.openapis.org/participate/how-to-contribute/governance#TDC). This group of committers bring their API expertise, incorporate feedback from the community, and expand the group of committers as appropriate. All development activity on the future specification will be performed as features and merged into this branch. Upon release of the future specification, this branch will be merged to `main`. + +The TSC holds weekly web conferences to review open pull requests and discuss open issues related to the evolving OpenAPI Specification. Participation in weekly calls and scheduled working sessions is open to the community. You can view the entire OpenAPI [technical meeting calendar](https://calendar.google.com/calendar/u/0/embed?src=c_fue82vsncog6ahhjvuokjo8qsk@group.calendar.google.com) online. -The TSC holds weekly web conferences to review open pull requests and discuss open issues related to the evolving OpenAPI Specification. Participation in weekly calls and scheduled working sessions is open to the community. You can view the [TSC calendar online](https://openapi.groups.io/g/tsc/calendar), and import it to your calendar using the [iCal link](https://openapi.groups.io/g/tsc/ics/1105671/1995679554/feed.ics). +The OpenAPI Initiative encourages participation from individuals and companies alike. If you want to participate in the evolution of the OpenAPI Specification, consider taking the following actions: -The Open API Initiative encourages participation from individuals and companies alike. If you want to participate in the evolution of the OpenAPI Specification, consider taking the following actions: +* Review the specification [markdown sources](versions) and [authoritative _source-of-truth_ HTML renderings](https://spec.openapis.org/), including full credits and citations. +* Review the [contributing](CONTRIBUTING.md) process so you understand how the spec is evolving. +* Check the [discussions](https://github.com/OAI/OpenAPI-Specification/discussions), [issues](https://github.com/OAI/OpenAPI-Specification/issues) and [pull requests](https://github.com/OAI/OpenAPI-Specification/pulls) to see if someone has already documented your idea or feedback on the specification. You can follow an existing conversation by subscribing to the existing issue or PR. +* Subscribe to an open issue a day (or a week) in your inbox via [CodeTriage.com](https://www.codetriage.com/oai/openapi-specification). +* Create a discussion to describe a new concern, ideally with clear explanations of related use cases. -* Review the [current specification](versions/3.0.1.md). The human-readable markdown file _is the source of truth_ for the specification. -* Review the [development](DEVELOPMENT.md) process so you understand how the spec is evolving. -* Check the [issues](https://github.com/OAI/OpenAPI-Specification/issues) and [pull requests](https://github.com/OAI/OpenAPI-Specification/pulls) to see if someone has already documented your idea or feedback on the specification. You can follow an existing conversation by adding a comment to the existing issue or PR. -* Create an issue to describe a new concern. If possible, propose a solution. +Not all feedback can be accommodated, and there may be solid arguments for or against a change being appropriate for the specification. -Not all feedback can be accommodated and there may be solid arguments for or against a change being appropriate for the specification. +## Licensing -## License +See: [License (Apache-2.0)](https://github.com/OAI/OpenAPI-Specification/blob/main/LICENSE) -See: [License (Apache-2.0)](https://github.com/OAI/OpenAPI-Specification/blob/master/LICENSE) -![Analytics](https://ga-beacon.appspot.com/UA-831873-42/readme.md?pixel) diff --git a/SECURITY_CONSIDERATIONS.md b/SECURITY_CONSIDERATIONS.md new file mode 100644 index 0000000000..794f435c07 --- /dev/null +++ b/SECURITY_CONSIDERATIONS.md @@ -0,0 +1,26 @@ +# Security Considerations + +## OpenAPI Document Formats + +OpenAPI documents use JSON, YAML, and JSON Schema, and therefore share their security considerations: + +- [JSON](https://www.iana.org/assignments/media-types/application/json) +- [YAML](https://www.iana.org/assignments/media-types/application/yaml) +- [JSON Schema Core](https://json-schema.org/draft/2020-12/json-schema-core#section-13) +- [JSON Schema Validation](https://json-schema.org/draft/2020-12/json-schema-validation#name-security-considerations) + +## Tooling and Usage Scenarios + +In addition, OpenAPI documents are processed by a wide variety of tooling for numerous different purposes, such as client code generation, documentation generation, server side routing, and API testing. OpenAPI document authors must consider the risks of the scenarios where the OpenAPI document may be used. + +## Security Schemes + +An OpenAPI document describes the security schemes used to protect the resources it defines. The security schemes available offer varying degrees of protection. Factors such as the sensitivity of the data and the potential impact of a security breach should guide the selection of security schemes for the API resources. Some security schemes, such as basic auth and OAuth Implicit flow, are supported for compatibility with existing APIs. However, their inclusion in OpenAPI does not constitute an endorsement of their use, particularly for highly sensitive data or operations. + +## Handling External Resources + +OpenAPI documents may contain references to external resources that may be dereferenced automatically by consuming tools. External resources may be hosted on different domains that may be untrusted. References in an OpenAPI document, or across OpenAPI documents may cause a cycle. Tooling must detect and handle cycles to prevent resource exhaustion. + +## Markdown and HTML Sanitization + +Certain properties allow the use of Markdown which can contain HTML including script. It is the responsibility of tooling to appropriately sanitize the Markdown. diff --git a/SPECIAL_INTEREST_GROUPS.md b/SPECIAL_INTEREST_GROUPS.md new file mode 100644 index 0000000000..661a757799 --- /dev/null +++ b/SPECIAL_INTEREST_GROUPS.md @@ -0,0 +1,5 @@ +# OpenAPI Special Interest Groups (SIGs) + +OpenAPI Special Interest Groups, or "SIGs", are the OpenAPI Initiative's way of focusing work in particular areas. SIGs may start with just a Slack channel to gauge interest. SIGs with enough traction to produce work may have their own GitHub repositories and regular Zoom calls, and ultimately produce work that becomes part of, or a companion to, the OpenAPI Specification. + +See the [OAS community repository](https://github.com/OAI/community/blob/main/SPECIAL_INTEREST_GROUPS.md) for a complete list of SIGs, and for more information about forming a SIG. diff --git a/TOB.md b/TOB.md new file mode 100644 index 0000000000..f325829b7e --- /dev/null +++ b/TOB.md @@ -0,0 +1,23 @@ +# Technical Oversight Board ("TOB") + +## Description + +> The TOB is responsible for managing conflicts, violations of procedures or guidelines or other issues that cannot be resolved in the TSC for the OAS. For further details please consult the OpenAPI Project Charter. + +## TSC Elected - terms through May 2023 + +Isabelle Mauny @isamauny + +Uri Sarid @usarid + +Marsh Gardiner @earth2marsh + +Ron Ratovsky @webron + +## BGB Elected - terms through May 2022 + +Darrel Miller @darrelmiller + +Jerome Louvel @jlouvel + +Jeremy Whitlock @whitlockjc diff --git a/_archive_/README.md b/_archive_/README.md new file mode 100644 index 0000000000..b5e176213e --- /dev/null +++ b/_archive_/README.md @@ -0,0 +1,3 @@ +# Archive + +This folder contains files that are no longer actively maintained. diff --git a/_archive_/schemas/README.md b/_archive_/schemas/README.md new file mode 100644 index 0000000000..78d9c18db0 --- /dev/null +++ b/_archive_/schemas/README.md @@ -0,0 +1,9 @@ +# Archive of outdated JSON Schema Files + +> [!TIP] +> JSON Schema files for validating OpenAPI descriptions using current OpenAPI versions are available on https://spec.openapis.org/#openapi-specification-schemas. +> +> These schema files are maintained in the `src/schemas` folder of the corresponding `vX.Y-dev` branch in this repository. + +> [!CAUTION] +> Schema files in this folder are not maintained any more and are not intended for productive use. diff --git a/schemas/v1.2/README.md b/_archive_/schemas/v1.2/README.md similarity index 100% rename from schemas/v1.2/README.md rename to _archive_/schemas/v1.2/README.md diff --git a/schemas/v1.2/apiDeclaration.json b/_archive_/schemas/v1.2/apiDeclaration.json similarity index 100% rename from schemas/v1.2/apiDeclaration.json rename to _archive_/schemas/v1.2/apiDeclaration.json diff --git a/schemas/v1.2/authorizationObject.json b/_archive_/schemas/v1.2/authorizationObject.json similarity index 100% rename from schemas/v1.2/authorizationObject.json rename to _archive_/schemas/v1.2/authorizationObject.json diff --git a/schemas/v1.2/dataType.json b/_archive_/schemas/v1.2/dataType.json similarity index 100% rename from schemas/v1.2/dataType.json rename to _archive_/schemas/v1.2/dataType.json diff --git a/schemas/v1.2/dataTypeBase.json b/_archive_/schemas/v1.2/dataTypeBase.json similarity index 100% rename from schemas/v1.2/dataTypeBase.json rename to _archive_/schemas/v1.2/dataTypeBase.json diff --git a/schemas/v1.2/infoObject.json b/_archive_/schemas/v1.2/infoObject.json similarity index 100% rename from schemas/v1.2/infoObject.json rename to _archive_/schemas/v1.2/infoObject.json diff --git a/schemas/v1.2/modelsObject.json b/_archive_/schemas/v1.2/modelsObject.json similarity index 100% rename from schemas/v1.2/modelsObject.json rename to _archive_/schemas/v1.2/modelsObject.json diff --git a/schemas/v1.2/oauth2GrantType.json b/_archive_/schemas/v1.2/oauth2GrantType.json similarity index 100% rename from schemas/v1.2/oauth2GrantType.json rename to _archive_/schemas/v1.2/oauth2GrantType.json diff --git a/schemas/v1.2/operationObject.json b/_archive_/schemas/v1.2/operationObject.json similarity index 97% rename from schemas/v1.2/operationObject.json rename to _archive_/schemas/v1.2/operationObject.json index 371a6cc82c..5661251eb7 100644 --- a/schemas/v1.2/operationObject.json +++ b/_archive_/schemas/v1.2/operationObject.json @@ -8,7 +8,7 @@ "required": [ "method", "nickname", "parameters" ], "properties": { "method": { "enum": [ "GET", "HEAD", "POST", "PUT", "PATCH", "DELETE", "OPTIONS" ] }, - "summary": { "type": "string", "maxLength": 120 }, + "summary": { "type": "string" }, "notes": { "type": "string" }, "nickname": { "type": "string", diff --git a/schemas/v1.2/parameterObject.json b/_archive_/schemas/v1.2/parameterObject.json similarity index 100% rename from schemas/v1.2/parameterObject.json rename to _archive_/schemas/v1.2/parameterObject.json diff --git a/schemas/v1.2/resourceListing.json b/_archive_/schemas/v1.2/resourceListing.json similarity index 100% rename from schemas/v1.2/resourceListing.json rename to _archive_/schemas/v1.2/resourceListing.json diff --git a/schemas/v1.2/resourceObject.json b/_archive_/schemas/v1.2/resourceObject.json similarity index 100% rename from schemas/v1.2/resourceObject.json rename to _archive_/schemas/v1.2/resourceObject.json diff --git a/_archive_/schemas/v2.0/README.md b/_archive_/schemas/v2.0/README.md new file mode 100644 index 0000000000..47b0c8e817 --- /dev/null +++ b/_archive_/schemas/v2.0/README.md @@ -0,0 +1,13 @@ +# OpenAPI Specification v2.0 JSON Schema + +This is the JSON Schema file for the OpenAPI Specification version 2.0. Download and install it via NPM. + +## Install via NPM + +```shell +npm install --save swagger-schema-official +``` + +## License + +Apache-2.0 diff --git a/schemas/v2.0/schema.json b/_archive_/schemas/v2.0/schema.json similarity index 100% rename from schemas/v2.0/schema.json rename to _archive_/schemas/v2.0/schema.json diff --git a/_archive_/schemas/v3.0/README.md b/_archive_/schemas/v3.0/README.md new file mode 100644 index 0000000000..5bda66cf5a --- /dev/null +++ b/_archive_/schemas/v3.0/README.md @@ -0,0 +1,43 @@ +# OpenAPI 3.0.X JSON Schema + +This directory contains the YAML source for generating the JSON Schema for validating OpenAPI definitions of versions 3.0.X, which is published on [https://spec.openapis.org](https://spec.openapis.org). + +Due to limitations of GitHub pages, the schemas on the spec site are served with `Content-Type: application/octet-stream`, but should be interpreted as `application/schema+json`. + +The source in this directory, which has `WORK-IN-PROGRESS` in its `id`, is _not intended for direct use_. + +## Schema `id` dates + +The published schemas on the spec site have an _iteration date_ in their `id`s. +This allows the schemas for a release line (in this case 3.0) to be updated independent of the spec patch release cycle. + +The iteration version of the JSON Schema can be found in the `id` field. +For example, the value of `id: https://spec.openapis.org/oas/3.0/schema/2019-04-02` means this iteration was created on April 2nd, 2019. + +We are [working on](https://github.com/OAI/OpenAPI-Specification/issues/4152) how to best provide programmatic access for determining the latest date for each schema. + +## Improving the schema + +As a reminder, the JSON Schema is not the source of truth for the Specification. +In cases of conflicts between the Specification itself and the JSON Schema, the Specification wins. +Also, some Specification constraints cannot be represented with the JSON Schema so it's highly recommended to employ other methods to ensure compliance. + +The schema only validates the mandatory aspects of the OAS. +Validating requirements that are optional, or field usage that has undefined or ignored behavior are not within the scope of this schema. +Schemas to perform additional optional validation are [under consideration](https://github.com/OAI/OpenAPI-Specification/issues/4141). + +Improvements can be submitted by opening a PR against the `main` branch. + +Modify the `schema.yaml` file and add test cases for your changes. + +The TSC will then: +- Run tests on the updated schema +- Update the iteration version +- Publish the new version + +The [test suite](../../tests/v3.0) is part of this package. + +```bash +npm install +npm test +``` diff --git a/examples/v3.0/api-with-examples.yaml b/_archive_/schemas/v3.0/pass/api-with-examples.yaml similarity index 86% rename from examples/v3.0/api-with-examples.yaml rename to _archive_/schemas/v3.0/pass/api-with-examples.yaml index dd42b0e959..18726a5476 100644 --- a/examples/v3.0/api-with-examples.yaml +++ b/_archive_/schemas/v3.0/pass/api-with-examples.yaml @@ -1,7 +1,7 @@ openapi: "3.0.0" info: title: Simple API overview - version: v2 + version: 2.0.0 paths: /: get: @@ -15,8 +15,9 @@ paths: application/json: examples: foo: - value: { - "versions": [ + value: + { + "versions": [ { "status": "CURRENT", "updated": "2011-01-21T11:33:21Z", @@ -39,8 +40,8 @@ paths: } ] } - ] - } + ] + } '300': description: |- 300 response @@ -87,11 +88,12 @@ paths: application/json: examples: foo: - value: { - "version": { - "status": "CURRENT", - "updated": "2011-01-21T11:33:21Z", - "media-types": [ + value: + { + "version": { + "status": "CURRENT", + "updated": "2011-01-21T11:33:21Z", + "media-types": [ { "base": "application/xml", "type": "application/vnd.openstack.compute+xml;version=2" @@ -100,9 +102,9 @@ paths: "base": "application/json", "type": "application/vnd.openstack.compute+json;version=2" } - ], - "id": "v2.0", - "links": [ + ], + "id": "v2.0", + "links": [ { "href": "http://127.0.0.1:8774/v2/", "rel": "self" @@ -122,9 +124,9 @@ paths: "type": "application/vnd.sun.wadl+xml", "rel": "describedby" } - ] + ] + } } - } '203': description: |- 203 response @@ -132,11 +134,12 @@ paths: application/json: examples: foo: - value: { - "version": { - "status": "CURRENT", - "updated": "2011-01-21T11:33:21Z", - "media-types": [ + value: + { + "version": { + "status": "CURRENT", + "updated": "2011-01-21T11:33:21Z", + "media-types": [ { "base": "application/xml", "type": "application/vnd.openstack.compute+xml;version=2" @@ -145,9 +148,9 @@ paths: "base": "application/json", "type": "application/vnd.openstack.compute+json;version=2" } - ], - "id": "v2.0", - "links": [ + ], + "id": "v2.0", + "links": [ { "href": "http://23.253.228.211:8774/v2/", "rel": "self" @@ -162,6 +165,6 @@ paths: "type": "application/vnd.sun.wadl+xml", "rel": "describedby" } - ] + ] + } } - } diff --git a/examples/v3.0/callback-example.yaml b/_archive_/schemas/v3.0/pass/callback-example.yaml similarity index 98% rename from examples/v3.0/callback-example.yaml rename to _archive_/schemas/v3.0/pass/callback-example.yaml index 1622bd06b1..262b8df518 100644 --- a/examples/v3.0/callback-example.yaml +++ b/_archive_/schemas/v3.0/pass/callback-example.yaml @@ -43,6 +43,7 @@ paths: content: application/json: schema: + type: object properties: timestamp: type: string diff --git a/examples/v3.0/link-example.yaml b/_archive_/schemas/v3.0/pass/link-example.yaml similarity index 100% rename from examples/v3.0/link-example.yaml rename to _archive_/schemas/v3.0/pass/link-example.yaml diff --git a/examples/v3.0/petstore-expanded.yaml b/_archive_/schemas/v3.0/pass/petstore-expanded.yaml similarity index 96% rename from examples/v3.0/petstore-expanded.yaml rename to _archive_/schemas/v3.0/pass/petstore-expanded.yaml index d7533318c6..7e5bff0efa 100644 --- a/examples/v3.0/petstore-expanded.yaml +++ b/_archive_/schemas/v3.0/pass/petstore-expanded.yaml @@ -12,7 +12,7 @@ info: name: Apache 2.0 url: https://www.apache.org/licenses/LICENSE-2.0.html servers: - - url: http://petstore.swagger.io/api + - url: https://petstore.swagger.io/v2 paths: /pets: get: @@ -55,7 +55,7 @@ paths: schema: $ref: '#/components/schemas/Error' post: - description: Creates a new pet in the store. Duplicates are allowed + description: Creates a new pet in the store. Duplicates are allowed operationId: addPet requestBody: description: Pet to add to the store @@ -127,7 +127,8 @@ components: Pet: allOf: - $ref: '#/components/schemas/NewPet' - - required: + - type: object + required: - id properties: id: @@ -135,6 +136,7 @@ components: format: int64 NewPet: + type: object required: - name properties: @@ -144,6 +146,7 @@ components: type: string Error: + type: object required: - code - message diff --git a/examples/v3.0/petstore.yaml b/_archive_/schemas/v3.0/pass/petstore.yaml similarity index 88% rename from examples/v3.0/petstore.yaml rename to _archive_/schemas/v3.0/pass/petstore.yaml index 5fdfba907d..7ed987ff63 100644 --- a/examples/v3.0/petstore.yaml +++ b/_archive_/schemas/v3.0/pass/petstore.yaml @@ -20,10 +20,11 @@ paths: required: false schema: type: integer + maximum: 100 format: int32 responses: '200': - description: An paged array of pets + description: A paged array of pets headers: x-next: description: A link to the next page of responses @@ -44,6 +45,12 @@ paths: operationId: createPets tags: - pets + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/Pet' + required: true responses: '201': description: Null response @@ -72,7 +79,7 @@ paths: content: application/json: schema: - $ref: "#/components/schemas/Pets" + $ref: "#/components/schemas/Pet" default: description: unexpected error content: @@ -82,6 +89,7 @@ paths: components: schemas: Pet: + type: object required: - id - name @@ -95,9 +103,11 @@ components: type: string Pets: type: array + maxItems: 100 items: $ref: "#/components/schemas/Pet" Error: + type: object required: - code - message diff --git a/examples/v3.0/uspto.yaml b/_archive_/schemas/v3.0/pass/uspto.yaml similarity index 96% rename from examples/v3.0/uspto.yaml rename to _archive_/schemas/v3.0/pass/uspto.yaml index 774ca526b6..d3011520d0 100644 --- a/examples/v3.0/uspto.yaml +++ b/_archive_/schemas/v3.0/pass/uspto.yaml @@ -1,4 +1,4 @@ -openapi: 3.0.0 +openapi: 3.0.1 servers: - url: '{scheme}://developer.uspto.gov/ds-api' variables: @@ -78,22 +78,22 @@ paths: parameters: - name: dataset in: path - description: 'Name of the dataset. In this case, the default value is oa_citations' + description: 'Name of the dataset.' required: true + example: "oa_citations" schema: type: string - default: oa_citations - name: version in: path description: Version of the dataset. required: true + example: "v1" schema: type: string - default: v1 responses: '200': description: >- - The dataset api for the given version is found and it is accessible + The dataset API for the given version is found and it is accessible to consume. content: application/json: @@ -115,7 +115,7 @@ paths: Provides search capability for the data set with the given search criteria. description: >- - This API is based on Solr/Lucense Search. The data is indexed using + This API is based on Solr/Lucene Search. The data is indexed using SOLR. This GET API returns the list of all the searchable field names that are in the Solr Index. Please see the 'fields' attribute which returns an array of field names. Each field or a combination of fields diff --git a/_archive_/schemas/v3.0/schema.test.mjs b/_archive_/schemas/v3.0/schema.test.mjs new file mode 100644 index 0000000000..fd413ed0a5 --- /dev/null +++ b/_archive_/schemas/v3.0/schema.test.mjs @@ -0,0 +1,42 @@ +import { readdirSync, readFileSync } from "node:fs"; +import YAML from "yaml"; +import { validate, setMetaSchemaOutputFormat } from "@hyperjump/json-schema/openapi-3-0"; +import { BASIC } from "@hyperjump/json-schema/experimental"; +import { describe, test, expect } from "vitest"; + +import contentTypeParser from "content-type"; +import { addMediaTypePlugin } from "@hyperjump/browser"; +import { buildSchemaDocument } from "@hyperjump/json-schema/experimental"; + +addMediaTypePlugin("application/schema+yaml", { + parse: async (response) => { + const contentType = contentTypeParser.parse(response.headers.get("content-type") ?? ""); + const contextDialectId = contentType.parameters.schema ?? contentType.parameters.profile; + + const foo = YAML.parse(await response.text()); + return buildSchemaDocument(foo, response.url, contextDialectId); + }, + fileMatcher: (path) => path.endsWith(".yaml") + }); + +const parseYamlFromFile = (filePath) => { + const schemaYaml = readFileSync(filePath, "utf8"); + return YAML.parse(schemaYaml, { prettyErrors: true }); +}; + +setMetaSchemaOutputFormat(BASIC); + +const validateOpenApi = await validate("./_archive_/schemas/v3.0/schema.yaml"); +const folder = './_archive_/schemas/v3.0/pass/'; + +describe("pass", async () => { + readdirSync(folder, { withFileTypes: true }) + .filter((entry) => entry.isFile() && /\.yaml$/.test(entry.name)) + .forEach((entry) => { + test(entry.name, () => { + const instance = parseYamlFromFile(folder + entry.name); + const output = validateOpenApi(instance, BASIC); + expect(output.valid).to.equal(true); + }); + }); +}); diff --git a/_archive_/schemas/v3.0/schema.yaml b/_archive_/schemas/v3.0/schema.yaml new file mode 100644 index 0000000000..acaf506eb5 --- /dev/null +++ b/_archive_/schemas/v3.0/schema.yaml @@ -0,0 +1,1031 @@ +id: https://spec.openapis.org/oas/3.0/schema/WORK-IN-PROGRESS +$schema: http://json-schema.org/draft-04/schema# +description: The description of OpenAPI v3.0.x Documents +type: object +required: + - openapi + - info + - paths +properties: + openapi: + type: string + pattern: ^3\.0\.\d(-.+)?$ + info: + $ref: '#/definitions/Info' + externalDocs: + $ref: '#/definitions/ExternalDocumentation' + servers: + type: array + items: + $ref: '#/definitions/Server' + security: + type: array + items: + $ref: '#/definitions/SecurityRequirement' + tags: + type: array + items: + $ref: '#/definitions/Tag' + uniqueItems: true + paths: + $ref: '#/definitions/Paths' + components: + $ref: '#/definitions/Components' +patternProperties: + '^x-': {} +additionalProperties: false +definitions: + Reference: + type: object + required: + - $ref + patternProperties: + '^\$ref$': + type: string + format: uri-reference + Info: + type: object + required: + - title + - version + properties: + title: + type: string + description: + type: string + termsOfService: + type: string + format: uri-reference + contact: + $ref: '#/definitions/Contact' + license: + $ref: '#/definitions/License' + version: + type: string + patternProperties: + '^x-': {} + additionalProperties: false + + + Contact: + type: object + properties: + name: + type: string + url: + type: string + format: uri-reference + email: + type: string + format: email + patternProperties: + '^x-': {} + additionalProperties: false + + License: + type: object + required: + - name + properties: + name: + type: string + url: + type: string + format: uri-reference + patternProperties: + '^x-': {} + additionalProperties: false + + Server: + type: object + required: + - url + properties: + url: + type: string + description: + type: string + variables: + type: object + additionalProperties: + $ref: '#/definitions/ServerVariable' + patternProperties: + '^x-': {} + additionalProperties: false + + ServerVariable: + type: object + required: + - default + properties: + enum: + type: array + items: + type: string + default: + type: string + description: + type: string + patternProperties: + '^x-': {} + additionalProperties: false + + Components: + type: object + properties: + schemas: + type: object + patternProperties: + '^[a-zA-Z0-9\.\-_]+$': + oneOf: + - $ref: '#/definitions/Schema' + - $ref: '#/definitions/Reference' + responses: + type: object + patternProperties: + '^[a-zA-Z0-9\.\-_]+$': + oneOf: + - $ref: '#/definitions/Reference' + - $ref: '#/definitions/Response' + parameters: + type: object + patternProperties: + '^[a-zA-Z0-9\.\-_]+$': + oneOf: + - $ref: '#/definitions/Reference' + - $ref: '#/definitions/Parameter' + examples: + type: object + patternProperties: + '^[a-zA-Z0-9\.\-_]+$': + oneOf: + - $ref: '#/definitions/Reference' + - $ref: '#/definitions/Example' + requestBodies: + type: object + patternProperties: + '^[a-zA-Z0-9\.\-_]+$': + oneOf: + - $ref: '#/definitions/Reference' + - $ref: '#/definitions/RequestBody' + headers: + type: object + patternProperties: + '^[a-zA-Z0-9\.\-_]+$': + oneOf: + - $ref: '#/definitions/Reference' + - $ref: '#/definitions/Header' + securitySchemes: + type: object + patternProperties: + '^[a-zA-Z0-9\.\-_]+$': + oneOf: + - $ref: '#/definitions/Reference' + - $ref: '#/definitions/SecurityScheme' + links: + type: object + patternProperties: + '^[a-zA-Z0-9\.\-_]+$': + oneOf: + - $ref: '#/definitions/Reference' + - $ref: '#/definitions/Link' + callbacks: + type: object + patternProperties: + '^[a-zA-Z0-9\.\-_]+$': + oneOf: + - $ref: '#/definitions/Reference' + - $ref: '#/definitions/Callback' + patternProperties: + '^x-': {} + additionalProperties: false + + Schema: + type: object + properties: + title: + type: string + multipleOf: + type: number + minimum: 0 + exclusiveMinimum: true + maximum: + type: number + exclusiveMaximum: + type: boolean + default: false + minimum: + type: number + exclusiveMinimum: + type: boolean + default: false + maxLength: + type: integer + minimum: 0 + minLength: + type: integer + minimum: 0 + default: 0 + pattern: + type: string + format: regex + maxItems: + type: integer + minimum: 0 + minItems: + type: integer + minimum: 0 + default: 0 + uniqueItems: + type: boolean + default: false + maxProperties: + type: integer + minimum: 0 + minProperties: + type: integer + minimum: 0 + default: 0 + required: + type: array + items: + type: string + minItems: 1 + uniqueItems: true + enum: + type: array + items: {} + minItems: 1 + uniqueItems: false + type: + type: string + enum: + - array + - boolean + - integer + - number + - object + - string + not: + oneOf: + - $ref: '#/definitions/Schema' + - $ref: '#/definitions/Reference' + allOf: + type: array + items: + oneOf: + - $ref: '#/definitions/Schema' + - $ref: '#/definitions/Reference' + oneOf: + type: array + items: + oneOf: + - $ref: '#/definitions/Schema' + - $ref: '#/definitions/Reference' + anyOf: + type: array + items: + oneOf: + - $ref: '#/definitions/Schema' + - $ref: '#/definitions/Reference' + items: + oneOf: + - $ref: '#/definitions/Schema' + - $ref: '#/definitions/Reference' + properties: + type: object + additionalProperties: + oneOf: + - $ref: '#/definitions/Schema' + - $ref: '#/definitions/Reference' + additionalProperties: + oneOf: + - $ref: '#/definitions/Schema' + - $ref: '#/definitions/Reference' + - type: boolean + default: true + description: + type: string + format: + type: string + default: {} + nullable: + type: boolean + default: false + discriminator: + $ref: '#/definitions/Discriminator' + readOnly: + type: boolean + default: false + writeOnly: + type: boolean + default: false + example: {} + externalDocs: + $ref: '#/definitions/ExternalDocumentation' + deprecated: + type: boolean + default: false + xml: + $ref: '#/definitions/XML' + patternProperties: + '^x-': {} + additionalProperties: false + + Discriminator: + type: object + required: + - propertyName + properties: + propertyName: + type: string + mapping: + type: object + additionalProperties: + type: string + + XML: + type: object + properties: + name: + type: string + namespace: + type: string + format: uri + prefix: + type: string + attribute: + type: boolean + default: false + wrapped: + type: boolean + default: false + patternProperties: + '^x-': {} + additionalProperties: false + + Response: + type: object + required: + - description + properties: + description: + type: string + headers: + type: object + additionalProperties: + oneOf: + - $ref: '#/definitions/Header' + - $ref: '#/definitions/Reference' + content: + type: object + additionalProperties: + $ref: '#/definitions/MediaType' + links: + type: object + additionalProperties: + oneOf: + - $ref: '#/definitions/Link' + - $ref: '#/definitions/Reference' + patternProperties: + '^x-': {} + additionalProperties: false + + MediaType: + type: object + properties: + schema: + oneOf: + - $ref: '#/definitions/Schema' + - $ref: '#/definitions/Reference' + example: {} + examples: + type: object + additionalProperties: + oneOf: + - $ref: '#/definitions/Example' + - $ref: '#/definitions/Reference' + encoding: + type: object + additionalProperties: + $ref: '#/definitions/Encoding' + patternProperties: + '^x-': {} + additionalProperties: false + allOf: + - $ref: '#/definitions/ExampleXORExamples' + + Example: + type: object + properties: + summary: + type: string + description: + type: string + value: {} + externalValue: + type: string + format: uri-reference + patternProperties: + '^x-': {} + additionalProperties: false + + Header: + type: object + properties: + description: + type: string + required: + type: boolean + default: false + deprecated: + type: boolean + default: false + allowEmptyValue: + type: boolean + default: false + style: + type: string + enum: + - simple + default: simple + explode: + type: boolean + allowReserved: + type: boolean + default: false + schema: + oneOf: + - $ref: '#/definitions/Schema' + - $ref: '#/definitions/Reference' + content: + type: object + additionalProperties: + $ref: '#/definitions/MediaType' + minProperties: 1 + maxProperties: 1 + example: {} + examples: + type: object + additionalProperties: + oneOf: + - $ref: '#/definitions/Example' + - $ref: '#/definitions/Reference' + patternProperties: + '^x-': {} + additionalProperties: false + allOf: + - $ref: '#/definitions/ExampleXORExamples' + - $ref: '#/definitions/SchemaXORContent' + + Paths: + type: object + patternProperties: + '^\/': + $ref: '#/definitions/PathItem' + '^x-': {} + additionalProperties: false + + PathItem: + type: object + properties: + $ref: + type: string + summary: + type: string + description: + type: string + get: + $ref: '#/definitions/Operation' + put: + $ref: '#/definitions/Operation' + post: + $ref: '#/definitions/Operation' + delete: + $ref: '#/definitions/Operation' + options: + $ref: '#/definitions/Operation' + head: + $ref: '#/definitions/Operation' + patch: + $ref: '#/definitions/Operation' + trace: + $ref: '#/definitions/Operation' + servers: + type: array + items: + $ref: '#/definitions/Server' + parameters: + type: array + items: + oneOf: + - $ref: '#/definitions/Parameter' + - $ref: '#/definitions/Reference' + uniqueItems: true + patternProperties: + '^x-': {} + additionalProperties: false + + Operation: + type: object + required: + - responses + properties: + tags: + type: array + items: + type: string + summary: + type: string + description: + type: string + externalDocs: + $ref: '#/definitions/ExternalDocumentation' + operationId: + type: string + parameters: + type: array + items: + oneOf: + - $ref: '#/definitions/Parameter' + - $ref: '#/definitions/Reference' + uniqueItems: true + requestBody: + oneOf: + - $ref: '#/definitions/RequestBody' + - $ref: '#/definitions/Reference' + responses: + $ref: '#/definitions/Responses' + callbacks: + type: object + additionalProperties: + oneOf: + - $ref: '#/definitions/Callback' + - $ref: '#/definitions/Reference' + deprecated: + type: boolean + default: false + security: + type: array + items: + $ref: '#/definitions/SecurityRequirement' + servers: + type: array + items: + $ref: '#/definitions/Server' + patternProperties: + '^x-': {} + additionalProperties: false + + Responses: + type: object + properties: + default: + oneOf: + - $ref: '#/definitions/Response' + - $ref: '#/definitions/Reference' + patternProperties: + '^[1-5](?:\d{2}|XX)$': + oneOf: + - $ref: '#/definitions/Response' + - $ref: '#/definitions/Reference' + '^x-': {} + minProperties: 1 + additionalProperties: false + + + SecurityRequirement: + type: object + additionalProperties: + type: array + items: + type: string + + Tag: + type: object + required: + - name + properties: + name: + type: string + description: + type: string + externalDocs: + $ref: '#/definitions/ExternalDocumentation' + patternProperties: + '^x-': {} + additionalProperties: false + + ExternalDocumentation: + type: object + required: + - url + properties: + description: + type: string + url: + type: string + format: uri-reference + patternProperties: + '^x-': {} + additionalProperties: false + + ExampleXORExamples: + description: Example and examples are mutually exclusive + not: + required: [example, examples] + + SchemaXORContent: + description: Schema and content are mutually exclusive, at least one is required + not: + required: [schema, content] + oneOf: + - required: [schema] + - required: [content] + description: Some properties are not allowed if content is present + allOf: + - not: + required: [style] + - not: + required: [explode] + - not: + required: [allowReserved] + - not: + required: [example] + - not: + required: [examples] + + Parameter: + type: object + properties: + name: + type: string + in: + type: string + description: + type: string + required: + type: boolean + default: false + deprecated: + type: boolean + default: false + allowEmptyValue: + type: boolean + default: false + style: + type: string + explode: + type: boolean + allowReserved: + type: boolean + default: false + schema: + oneOf: + - $ref: '#/definitions/Schema' + - $ref: '#/definitions/Reference' + content: + type: object + additionalProperties: + $ref: '#/definitions/MediaType' + minProperties: 1 + maxProperties: 1 + example: {} + examples: + type: object + additionalProperties: + oneOf: + - $ref: '#/definitions/Example' + - $ref: '#/definitions/Reference' + patternProperties: + '^x-': {} + additionalProperties: false + required: + - name + - in + allOf: + - $ref: '#/definitions/ExampleXORExamples' + - $ref: '#/definitions/SchemaXORContent' + oneOf: + - $ref: '#/definitions/PathParameter' + - $ref: '#/definitions/QueryParameter' + - $ref: '#/definitions/HeaderParameter' + - $ref: '#/definitions/CookieParameter' + + PathParameter: + description: Parameter in path + required: + - required + properties: + in: + enum: [path] + style: + enum: [matrix, label, simple] + default: simple + required: + enum: [true] + + QueryParameter: + description: Parameter in query + properties: + in: + enum: [query] + style: + enum: [form, spaceDelimited, pipeDelimited, deepObject] + default: form + + HeaderParameter: + description: Parameter in header + properties: + in: + enum: [header] + style: + enum: [simple] + default: simple + + CookieParameter: + description: Parameter in cookie + properties: + in: + enum: [cookie] + style: + enum: [form] + default: form + + RequestBody: + type: object + required: + - content + properties: + description: + type: string + content: + type: object + additionalProperties: + $ref: '#/definitions/MediaType' + required: + type: boolean + default: false + patternProperties: + '^x-': {} + additionalProperties: false + + SecurityScheme: + oneOf: + - $ref: '#/definitions/APIKeySecurityScheme' + - $ref: '#/definitions/HTTPSecurityScheme' + - $ref: '#/definitions/OAuth2SecurityScheme' + - $ref: '#/definitions/OpenIdConnectSecurityScheme' + + APIKeySecurityScheme: + type: object + required: + - type + - name + - in + properties: + type: + type: string + enum: + - apiKey + name: + type: string + in: + type: string + enum: + - header + - query + - cookie + description: + type: string + patternProperties: + '^x-': {} + additionalProperties: false + + HTTPSecurityScheme: + type: object + required: + - scheme + - type + properties: + scheme: + type: string + bearerFormat: + type: string + description: + type: string + type: + type: string + enum: + - http + patternProperties: + '^x-': {} + additionalProperties: false + oneOf: + - description: Bearer + properties: + scheme: + type: string + pattern: ^[Bb][Ee][Aa][Rr][Ee][Rr]$ + + - description: Non Bearer + not: + required: [bearerFormat] + properties: + scheme: + not: + type: string + pattern: ^[Bb][Ee][Aa][Rr][Ee][Rr]$ + + OAuth2SecurityScheme: + type: object + required: + - type + - flows + properties: + type: + type: string + enum: + - oauth2 + flows: + $ref: '#/definitions/OAuthFlows' + description: + type: string + patternProperties: + '^x-': {} + additionalProperties: false + + OpenIdConnectSecurityScheme: + type: object + required: + - type + - openIdConnectUrl + properties: + type: + type: string + enum: + - openIdConnect + openIdConnectUrl: + type: string + format: uri-reference + description: + type: string + patternProperties: + '^x-': {} + additionalProperties: false + + OAuthFlows: + type: object + properties: + implicit: + $ref: '#/definitions/ImplicitOAuthFlow' + password: + $ref: '#/definitions/PasswordOAuthFlow' + clientCredentials: + $ref: '#/definitions/ClientCredentialsFlow' + authorizationCode: + $ref: '#/definitions/AuthorizationCodeOAuthFlow' + patternProperties: + '^x-': {} + additionalProperties: false + + ImplicitOAuthFlow: + type: object + required: + - authorizationUrl + - scopes + properties: + authorizationUrl: + type: string + format: uri-reference + refreshUrl: + type: string + format: uri-reference + scopes: + type: object + additionalProperties: + type: string + patternProperties: + '^x-': {} + additionalProperties: false + + PasswordOAuthFlow: + type: object + required: + - tokenUrl + - scopes + properties: + tokenUrl: + type: string + format: uri-reference + refreshUrl: + type: string + format: uri-reference + scopes: + type: object + additionalProperties: + type: string + patternProperties: + '^x-': {} + additionalProperties: false + + ClientCredentialsFlow: + type: object + required: + - tokenUrl + - scopes + properties: + tokenUrl: + type: string + format: uri-reference + refreshUrl: + type: string + format: uri-reference + scopes: + type: object + additionalProperties: + type: string + patternProperties: + '^x-': {} + additionalProperties: false + + AuthorizationCodeOAuthFlow: + type: object + required: + - authorizationUrl + - tokenUrl + - scopes + properties: + authorizationUrl: + type: string + format: uri-reference + tokenUrl: + type: string + format: uri-reference + refreshUrl: + type: string + format: uri-reference + scopes: + type: object + additionalProperties: + type: string + patternProperties: + '^x-': {} + additionalProperties: false + + Link: + type: object + properties: + operationId: + type: string + operationRef: + type: string + format: uri-reference + parameters: + type: object + additionalProperties: {} + requestBody: {} + description: + type: string + server: + $ref: '#/definitions/Server' + patternProperties: + '^x-': {} + additionalProperties: false + not: + description: Operation Id and Operation Ref are mutually exclusive + required: [operationId, operationRef] + + Callback: + type: object + additionalProperties: + $ref: '#/definitions/PathItem' + patternProperties: + '^x-': {} + + Encoding: + type: object + properties: + contentType: + type: string + headers: + type: object + additionalProperties: + oneOf: + - $ref: '#/definitions/Header' + - $ref: '#/definitions/Reference' + style: + type: string + enum: + - form + - spaceDelimited + - pipeDelimited + - deepObject + explode: + type: boolean + allowReserved: + type: boolean + default: false + patternProperties: + '^x-': {} + additionalProperties: false diff --git a/examples/v2.0/json/api-with-examples.json b/examples/v2.0/json/api-with-examples.json deleted file mode 100644 index e1b371a070..0000000000 --- a/examples/v2.0/json/api-with-examples.json +++ /dev/null @@ -1,58 +0,0 @@ -{ - "swagger": "2.0", - "info": { - "title": "Simple API overview", - "version": "v2" - }, - "paths": { - "/": { - "get": { - "operationId": "listVersionsv2", - "summary": "List API versions", - "produces": [ - "application/json" - ], - "responses": { - "200": { - "description": "200 300 response", - "examples": { - "application/json": "{\n \"versions\": [\n {\n \"status\": \"CURRENT\",\n \"updated\": \"2011-01-21T11:33:21Z\",\n \"id\": \"v2.0\",\n \"links\": [\n {\n \"href\": \"http://127.0.0.1:8774/v2/\",\n \"rel\": \"self\"\n }\n ]\n },\n {\n \"status\": \"EXPERIMENTAL\",\n \"updated\": \"2013-07-23T11:33:21Z\",\n \"id\": \"v3.0\",\n \"links\": [\n {\n \"href\": \"http://127.0.0.1:8774/v3/\",\n \"rel\": \"self\"\n }\n ]\n }\n ]\n}" - } - }, - "300": { - "description": "200 300 response", - "examples": { - "application/json": "{\n \"versions\": [\n {\n \"status\": \"CURRENT\",\n \"updated\": \"2011-01-21T11:33:21Z\",\n \"id\": \"v2.0\",\n \"links\": [\n {\n \"href\": \"http://127.0.0.1:8774/v2/\",\n \"rel\": \"self\"\n }\n ]\n },\n {\n \"status\": \"EXPERIMENTAL\",\n \"updated\": \"2013-07-23T11:33:21Z\",\n \"id\": \"v3.0\",\n \"links\": [\n {\n \"href\": \"http://127.0.0.1:8774/v3/\",\n \"rel\": \"self\"\n }\n ]\n }\n ]\n}" - } - } - } - } - }, - "/v2": { - "get": { - "operationId": "getVersionDetailsv2", - "summary": "Show API version details", - "produces": [ - "application/json" - ], - "responses": { - "200": { - "description": "200 203 response", - "examples": { - "application/json": "{\n \"version\": {\n \"status\": \"CURRENT\",\n \"updated\": \"2011-01-21T11:33:21Z\",\n \"media-types\": [\n {\n \"base\": \"application/xml\",\n \"type\": \"application/vnd.openstack.compute+xml;version=2\"\n },\n {\n \"base\": \"application/json\",\n \"type\": \"application/vnd.openstack.compute+json;version=2\"\n }\n ],\n \"id\": \"v2.0\",\n \"links\": [\n {\n \"href\": \"http://127.0.0.1:8774/v2/\",\n \"rel\": \"self\"\n },\n {\n \"href\": \"http://docs.openstack.org/api/openstack-compute/2/os-compute-devguide-2.pdf\",\n \"type\": \"application/pdf\",\n \"rel\": \"describedby\"\n },\n {\n \"href\": \"http://docs.openstack.org/api/openstack-compute/2/wadl/os-compute-2.wadl\",\n \"type\": \"application/vnd.sun.wadl+xml\",\n \"rel\": \"describedby\"\n },\n {\n \"href\": \"http://docs.openstack.org/api/openstack-compute/2/wadl/os-compute-2.wadl\",\n \"type\": \"application/vnd.sun.wadl+xml\",\n \"rel\": \"describedby\"\n }\n ]\n }\n}" - } - }, - "203": { - "description": "200 203 response", - "examples": { - "application/json": "{\n \"version\": {\n \"status\": \"CURRENT\",\n \"updated\": \"2011-01-21T11:33:21Z\",\n \"media-types\": [\n {\n \"base\": \"application/xml\",\n \"type\": \"application/vnd.openstack.compute+xml;version=2\"\n },\n {\n \"base\": \"application/json\",\n \"type\": \"application/vnd.openstack.compute+json;version=2\"\n }\n ],\n \"id\": \"v2.0\",\n \"links\": [\n {\n \"href\": \"http://23.253.228.211:8774/v2/\",\n \"rel\": \"self\"\n },\n {\n \"href\": \"http://docs.openstack.org/api/openstack-compute/2/os-compute-devguide-2.pdf\",\n \"type\": \"application/pdf\",\n \"rel\": \"describedby\"\n },\n {\n \"href\": \"http://docs.openstack.org/api/openstack-compute/2/wadl/os-compute-2.wadl\",\n \"type\": \"application/vnd.sun.wadl+xml\",\n \"rel\": \"describedby\"\n }\n ]\n }\n}" - } - } - } - } - } - }, - "consumes": [ - "application/json" - ] -} \ No newline at end of file diff --git a/examples/v2.0/json/petstore-expanded.json b/examples/v2.0/json/petstore-expanded.json deleted file mode 100644 index d5d8de8126..0000000000 --- a/examples/v2.0/json/petstore-expanded.json +++ /dev/null @@ -1,210 +0,0 @@ -{ - "swagger": "2.0", - "info": { - "version": "1.0.0", - "title": "Swagger Petstore", - "description": "A sample API that uses a petstore as an example to demonstrate features in the swagger-2.0 specification", - "termsOfService": "http://swagger.io/terms/", - "contact": { - "name": "Swagger API Team", - "email": "apiteam@swagger.io", - "url": "http://swagger.io" - }, - "license": { - "name": "Apache 2.0", - "url": "https://www.apache.org/licenses/LICENSE-2.0.html" - } - }, - "host": "petstore.swagger.io", - "basePath": "/api", - "schemes": [ - "http" - ], - "consumes": [ - "application/json" - ], - "produces": [ - "application/json" - ], - "paths": { - "/pets": { - "get": { - "description": "Returns all pets from the system that the user has access to\nNam sed condimentum est. Maecenas tempor sagittis sapien, nec rhoncus sem sagittis sit amet. Aenean at gravida augue, ac iaculis sem. Curabitur odio lorem, ornare eget elementum nec, cursus id lectus. Duis mi turpis, pulvinar ac eros ac, tincidunt varius justo. In hac habitasse platea dictumst. Integer at adipiscing ante, a sagittis ligula. Aenean pharetra tempor ante molestie imperdiet. Vivamus id aliquam diam. Cras quis velit non tortor eleifend sagittis. Praesent at enim pharetra urna volutpat venenatis eget eget mauris. In eleifend fermentum facilisis. Praesent enim enim, gravida ac sodales sed, placerat id erat. Suspendisse lacus dolor, consectetur non augue vel, vehicula interdum libero. Morbi euismod sagittis libero sed lacinia.\n\nSed tempus felis lobortis leo pulvinar rutrum. Nam mattis velit nisl, eu condimentum ligula luctus nec. Phasellus semper velit eget aliquet faucibus. In a mattis elit. Phasellus vel urna viverra, condimentum lorem id, rhoncus nibh. Ut pellentesque posuere elementum. Sed a varius odio. Morbi rhoncus ligula libero, vel eleifend nunc tristique vitae. Fusce et sem dui. Aenean nec scelerisque tortor. Fusce malesuada accumsan magna vel tempus. Quisque mollis felis eu dolor tristique, sit amet auctor felis gravida. Sed libero lorem, molestie sed nisl in, accumsan tempor nisi. Fusce sollicitudin massa ut lacinia mattis. Sed vel eleifend lorem. Pellentesque vitae felis pretium, pulvinar elit eu, euismod sapien.\n", - "operationId": "findPets", - "parameters": [ - { - "name": "tags", - "in": "query", - "description": "tags to filter by", - "required": false, - "type": "array", - "collectionFormat": "csv", - "items": { - "type": "string" - } - }, - { - "name": "limit", - "in": "query", - "description": "maximum number of results to return", - "required": false, - "type": "integer", - "format": "int32" - } - ], - "responses": { - "200": { - "description": "pet response", - "schema": { - "type": "array", - "items": { - "$ref": "#/definitions/Pet" - } - } - }, - "default": { - "description": "unexpected error", - "schema": { - "$ref": "#/definitions/Error" - } - } - } - }, - "post": { - "description": "Creates a new pet in the store. Duplicates are allowed", - "operationId": "addPet", - "parameters": [ - { - "name": "pet", - "in": "body", - "description": "Pet to add to the store", - "required": true, - "schema": { - "$ref": "#/definitions/NewPet" - } - } - ], - "responses": { - "200": { - "description": "pet response", - "schema": { - "$ref": "#/definitions/Pet" - } - }, - "default": { - "description": "unexpected error", - "schema": { - "$ref": "#/definitions/Error" - } - } - } - } - }, - "/pets/{id}": { - "get": { - "description": "Returns a user based on a single ID, if the user does not have access to the pet", - "operationId": "find pet by id", - "parameters": [ - { - "name": "id", - "in": "path", - "description": "ID of pet to fetch", - "required": true, - "type": "integer", - "format": "int64" - } - ], - "responses": { - "200": { - "description": "pet response", - "schema": { - "$ref": "#/definitions/Pet" - } - }, - "default": { - "description": "unexpected error", - "schema": { - "$ref": "#/definitions/Error" - } - } - } - }, - "delete": { - "description": "deletes a single pet based on the ID supplied", - "operationId": "deletePet", - "parameters": [ - { - "name": "id", - "in": "path", - "description": "ID of pet to delete", - "required": true, - "type": "integer", - "format": "int64" - } - ], - "responses": { - "204": { - "description": "pet deleted" - }, - "default": { - "description": "unexpected error", - "schema": { - "$ref": "#/definitions/Error" - } - } - } - } - } - }, - "definitions": { - "Pet": { - "type": "object", - "allOf": [ - { - "$ref": "#/definitions/NewPet" - }, - { - "required": [ - "id" - ], - "properties": { - "id": { - "type": "integer", - "format": "int64" - } - } - } - ] - }, - "NewPet": { - "type": "object", - "required": [ - "name" - ], - "properties": { - "name": { - "type": "string" - }, - "tag": { - "type": "string" - } - } - }, - "Error": { - "type": "object", - "required": [ - "code", - "message" - ], - "properties": { - "code": { - "type": "integer", - "format": "int32" - }, - "message": { - "type": "string" - } - } - } - } -} diff --git a/examples/v2.0/json/petstore-minimal.json b/examples/v2.0/json/petstore-minimal.json deleted file mode 100644 index 0c70baed7e..0000000000 --- a/examples/v2.0/json/petstore-minimal.json +++ /dev/null @@ -1,68 +0,0 @@ -{ - "swagger": "2.0", - "info": { - "version": "1.0.0", - "title": "Swagger Petstore", - "description": "A sample API that uses a petstore as an example to demonstrate features in the swagger-2.0 specification", - "termsOfService": "http://swagger.io/terms/", - "contact": { - "name": "Swagger API Team" - }, - "license": { - "name": "MIT" - } - }, - "host": "petstore.swagger.io", - "basePath": "/api", - "schemes": [ - "http" - ], - "consumes": [ - "application/json" - ], - "produces": [ - "application/json" - ], - "paths": { - "/pets": { - "get": { - "description": "Returns all pets from the system that the user has access to", - "produces": [ - "application/json" - ], - "responses": { - "200": { - "description": "A list of pets.", - "schema": { - "type": "array", - "items": { - "$ref": "#/definitions/Pet" - } - } - } - } - } - } - }, - "definitions": { - "Pet": { - "type": "object", - "required": [ - "id", - "name" - ], - "properties": { - "id": { - "type": "integer", - "format": "int64" - }, - "name": { - "type": "string" - }, - "tag": { - "type": "string" - } - } - } - } -} \ No newline at end of file diff --git a/examples/v2.0/json/petstore-separate/common/Error.json b/examples/v2.0/json/petstore-separate/common/Error.json deleted file mode 100644 index dd0e65a0fa..0000000000 --- a/examples/v2.0/json/petstore-separate/common/Error.json +++ /dev/null @@ -1,16 +0,0 @@ -{ - "type": "object", - "required": [ - "code", - "message" - ], - "properties": { - "code": { - "type": "integer", - "format": "int32" - }, - "message": { - "type": "string" - } - } -} \ No newline at end of file diff --git a/examples/v2.0/json/petstore-separate/spec/NewPet.json b/examples/v2.0/json/petstore-separate/spec/NewPet.json deleted file mode 100644 index 9104f7f68a..0000000000 --- a/examples/v2.0/json/petstore-separate/spec/NewPet.json +++ /dev/null @@ -1,19 +0,0 @@ -{ - "type": "object", - "allOf": [ - { - "$ref": "Pet.json" - }, - { - "required": [ - "name" - ], - "properties": { - "description": { - "type": "integer", - "format": "int64" - } - } - } - ] -} \ No newline at end of file diff --git a/examples/v2.0/json/petstore-separate/spec/Pet.json b/examples/v2.0/json/petstore-separate/spec/Pet.json deleted file mode 100644 index c7ee9fbb05..0000000000 --- a/examples/v2.0/json/petstore-separate/spec/Pet.json +++ /dev/null @@ -1,19 +0,0 @@ -{ - "type": "object", - "required": [ - "id", - "name" - ], - "properties": { - "id": { - "type": "integer", - "format": "int64" - }, - "name": { - "type": "string" - }, - "tag": { - "type": "string" - } - } -} \ No newline at end of file diff --git a/examples/v2.0/json/petstore-separate/spec/parameters.json b/examples/v2.0/json/petstore-separate/spec/parameters.json deleted file mode 100644 index a7c11b0a0c..0000000000 --- a/examples/v2.0/json/petstore-separate/spec/parameters.json +++ /dev/null @@ -1,21 +0,0 @@ -{ - "tagsParam": { - "name": "tags", - "in": "query", - "description": "tags to filter by", - "required": false, - "type": "array", - "collectionFormat": "csv", - "items": { - "type": "string" - } - }, - "limitsParam": { - "name": "limit", - "in": "query", - "description": "maximum number of results to return", - "required": false, - "type": "integer", - "format": "int32" - } -} \ No newline at end of file diff --git a/examples/v2.0/json/petstore-separate/spec/swagger.json b/examples/v2.0/json/petstore-separate/spec/swagger.json deleted file mode 100644 index 7276990020..0000000000 --- a/examples/v2.0/json/petstore-separate/spec/swagger.json +++ /dev/null @@ -1,146 +0,0 @@ -{ - "swagger": "2.0", - "info": { - "version": "1.0.0", - "title": "Swagger Petstore", - "description": "A sample API that uses a petstore as an example to demonstrate features in the swagger-2.0 specification", - "termsOfService": "http://swagger.io/terms/", - "contact": { - "name": "Swagger API Team", - "email": "apiteam@swagger.io", - "url": "http://swagger.io" - }, - "license": { - "name": "Apache 2.0", - "url": "https://www.apache.org/licenses/LICENSE-2.0.html" - } - }, - "host": "petstore.swagger.io", - "basePath": "/api", - "schemes": [ - "http" - ], - "consumes": [ - "application/json" - ], - "produces": [ - "application/json" - ], - "paths": { - "/pets": { - "get": { - "description": "Returns all pets from the system that the user has access to\nNam sed condimentum est. Maecenas tempor sagittis sapien, nec rhoncus sem sagittis sit amet. Aenean at gravida augue, ac iaculis sem. Curabitur odio lorem, ornare eget elementum nec, cursus id lectus. Duis mi turpis, pulvinar ac eros ac, tincidunt varius justo. In hac habitasse platea dictumst. Integer at adipiscing ante, a sagittis ligula. Aenean pharetra tempor ante molestie imperdiet. Vivamus id aliquam diam. Cras quis velit non tortor eleifend sagittis. Praesent at enim pharetra urna volutpat venenatis eget eget mauris. In eleifend fermentum facilisis. Praesent enim enim, gravida ac sodales sed, placerat id erat. Suspendisse lacus dolor, consectetur non augue vel, vehicula interdum libero. Morbi euismod sagittis libero sed lacinia.\n\nSed tempus felis lobortis leo pulvinar rutrum. Nam mattis velit nisl, eu condimentum ligula luctus nec. Phasellus semper velit eget aliquet faucibus. In a mattis elit. Phasellus vel urna viverra, condimentum lorem id, rhoncus nibh. Ut pellentesque posuere elementum. Sed a varius odio. Morbi rhoncus ligula libero, vel eleifend nunc tristique vitae. Fusce et sem dui. Aenean nec scelerisque tortor. Fusce malesuada accumsan magna vel tempus. Quisque mollis felis eu dolor tristique, sit amet auctor felis gravida. Sed libero lorem, molestie sed nisl in, accumsan tempor nisi. Fusce sollicitudin massa ut lacinia mattis. Sed vel eleifend lorem. Pellentesque vitae felis pretium, pulvinar elit eu, euismod sapien.\n", - "operationId": "findPets", - "parameters": [ - { - "$ref": "parameters.json#/tagsParam" - }, - { - "$ref": "parameters.json#/limitsParam" - } - ], - "responses": { - "200": { - "description": "pet response", - "schema": { - "type": "array", - "items": { - "$ref": "Pet.json" - } - } - }, - "default": { - "description": "unexpected error", - "schema": { - "$ref": "../common/Error.json" - } - } - } - }, - "post": { - "description": "Creates a new pet in the store. Duplicates are allowed", - "operationId": "addPet", - "parameters": [ - { - "name": "pet", - "in": "body", - "description": "Pet to add to the store", - "required": true, - "schema": { - "$ref": "NewPet.json" - } - } - ], - "responses": { - "200": { - "description": "pet response", - "schema": { - "$ref": "Pet.json" - } - }, - "default": { - "description": "unexpected error", - "schema": { - "$ref": "../common/Error.json" - } - } - } - } - }, - "/pets/{id}": { - "get": { - "description": "Returns a user based on a single ID, if the user does not have access to the pet", - "operationId": "find pet by id", - "parameters": [ - { - "name": "id", - "in": "path", - "description": "ID of pet to fetch", - "required": true, - "type": "integer", - "format": "int64" - } - ], - "responses": { - "200": { - "description": "pet response", - "schema": { - "$ref": "Pet.json" - } - }, - "default": { - "description": "unexpected error", - "schema": { - "$ref": "../common/Error.json" - } - } - } - }, - "delete": { - "description": "deletes a single pet based on the ID supplied", - "operationId": "deletePet", - "parameters": [ - { - "name": "id", - "in": "path", - "description": "ID of pet to delete", - "required": true, - "type": "integer", - "format": "int64" - } - ], - "responses": { - "204": { - "description": "pet deleted" - }, - "default": { - "description": "unexpected error", - "schema": { - "$ref": "../common/Error.json" - } - } - } - } - } - } -} diff --git a/examples/v2.0/json/petstore-simple.json b/examples/v2.0/json/petstore-simple.json deleted file mode 100644 index 306dc90c9c..0000000000 --- a/examples/v2.0/json/petstore-simple.json +++ /dev/null @@ -1,222 +0,0 @@ -{ - "swagger": "2.0", - "info": { - "version": "1.0.0", - "title": "Swagger Petstore", - "description": "A sample API that uses a petstore as an example to demonstrate features in the swagger-2.0 specification", - "termsOfService": "http://swagger.io/terms/", - "contact": { - "name": "Swagger API Team" - }, - "license": { - "name": "MIT" - } - }, - "host": "petstore.swagger.io", - "basePath": "/api", - "schemes": [ - "http" - ], - "consumes": [ - "application/json" - ], - "produces": [ - "application/json" - ], - "paths": { - "/pets": { - "get": { - "description": "Returns all pets from the system that the user has access to", - "operationId": "findPets", - "produces": [ - "application/json", - "application/xml", - "text/xml", - "text/html" - ], - "parameters": [ - { - "name": "tags", - "in": "query", - "description": "tags to filter by", - "required": false, - "type": "array", - "items": { - "type": "string" - }, - "collectionFormat": "csv" - }, - { - "name": "limit", - "in": "query", - "description": "maximum number of results to return", - "required": false, - "type": "integer", - "format": "int32" - } - ], - "responses": { - "200": { - "description": "pet response", - "schema": { - "type": "array", - "items": { - "$ref": "#/definitions/Pet" - } - } - }, - "default": { - "description": "unexpected error", - "schema": { - "$ref": "#/definitions/ErrorModel" - } - } - } - }, - "post": { - "description": "Creates a new pet in the store. Duplicates are allowed", - "operationId": "addPet", - "produces": [ - "application/json" - ], - "parameters": [ - { - "name": "pet", - "in": "body", - "description": "Pet to add to the store", - "required": true, - "schema": { - "$ref": "#/definitions/NewPet" - } - } - ], - "responses": { - "200": { - "description": "pet response", - "schema": { - "$ref": "#/definitions/Pet" - } - }, - "default": { - "description": "unexpected error", - "schema": { - "$ref": "#/definitions/ErrorModel" - } - } - } - } - }, - "/pets/{id}": { - "get": { - "description": "Returns a user based on a single ID, if the user does not have access to the pet", - "operationId": "findPetById", - "produces": [ - "application/json", - "application/xml", - "text/xml", - "text/html" - ], - "parameters": [ - { - "name": "id", - "in": "path", - "description": "ID of pet to fetch", - "required": true, - "type": "integer", - "format": "int64" - } - ], - "responses": { - "200": { - "description": "pet response", - "schema": { - "$ref": "#/definitions/Pet" - } - }, - "default": { - "description": "unexpected error", - "schema": { - "$ref": "#/definitions/ErrorModel" - } - } - } - }, - "delete": { - "description": "deletes a single pet based on the ID supplied", - "operationId": "deletePet", - "parameters": [ - { - "name": "id", - "in": "path", - "description": "ID of pet to delete", - "required": true, - "type": "integer", - "format": "int64" - } - ], - "responses": { - "204": { - "description": "pet deleted" - }, - "default": { - "description": "unexpected error", - "schema": { - "$ref": "#/definitions/ErrorModel" - } - } - } - } - } - }, - "definitions": { - "Pet": { - "type": "object", - "allOf": [ - { - "$ref": "#/definitions/NewPet" - }, - { - "required": [ - "id" - ], - "properties": { - "id": { - "type": "integer", - "format": "int64" - } - } - } - ] - }, - "NewPet": { - "type": "object", - "required": [ - "name" - ], - "properties": { - "name": { - "type": "string" - }, - "tag": { - "type": "string" - } - } - }, - "ErrorModel": { - "type": "object", - "required": [ - "code", - "message" - ], - "properties": { - "code": { - "type": "integer", - "format": "int32" - }, - "message": { - "type": "string" - } - } - } - } -} \ No newline at end of file diff --git a/examples/v2.0/json/petstore-with-external-docs.json b/examples/v2.0/json/petstore-with-external-docs.json deleted file mode 100644 index e9d3f7765d..0000000000 --- a/examples/v2.0/json/petstore-with-external-docs.json +++ /dev/null @@ -1,233 +0,0 @@ -{ - "swagger": "2.0", - "info": { - "version": "1.0.0", - "title": "Swagger Petstore", - "description": "A sample API that uses a petstore as an example to demonstrate features in the swagger-2.0 specification", - "termsOfService": "http://swagger.io/terms/", - "contact": { - "name": "Swagger API Team", - "email": "apiteam@swagger.io", - "url": "http://swagger.io" - }, - "license": { - "name": "Apache 2.0", - "url": "https://www.apache.org/licenses/LICENSE-2.0.html" - } - }, - "externalDocs": { - "description": "find more info here", - "url": "https://swagger.io/about" - }, - "host": "petstore.swagger.io", - "basePath": "/api", - "schemes": [ - "http" - ], - "consumes": [ - "application/json" - ], - "produces": [ - "application/json" - ], - "paths": { - "/pets": { - "get": { - "description": "Returns all pets from the system that the user has access to", - "operationId": "findPets", - "externalDocs": { - "description": "find more info here", - "url": "https://swagger.io/about" - }, - "produces": [ - "application/json", - "application/xml", - "text/xml", - "text/html" - ], - "parameters": [ - { - "name": "tags", - "in": "query", - "description": "tags to filter by", - "required": false, - "type": "array", - "items": { - "type": "string" - }, - "collectionFormat": "csv" - }, - { - "name": "limit", - "in": "query", - "description": "maximum number of results to return", - "required": false, - "type": "integer", - "format": "int32" - } - ], - "responses": { - "200": { - "description": "pet response", - "schema": { - "type": "array", - "items": { - "$ref": "#/definitions/Pet" - } - } - }, - "default": { - "description": "unexpected error", - "schema": { - "$ref": "#/definitions/ErrorModel" - } - } - } - }, - "post": { - "description": "Creates a new pet in the store. Duplicates are allowed", - "operationId": "addPet", - "produces": [ - "application/json" - ], - "parameters": [ - { - "name": "pet", - "in": "body", - "description": "Pet to add to the store", - "required": true, - "schema": { - "$ref": "#/definitions/NewPet" - } - } - ], - "responses": { - "200": { - "description": "pet response", - "schema": { - "$ref": "#/definitions/Pet" - } - }, - "default": { - "description": "unexpected error", - "schema": { - "$ref": "#/definitions/ErrorModel" - } - } - } - } - }, - "/pets/{id}": { - "get": { - "description": "Returns a user based on a single ID, if the user does not have access to the pet", - "operationId": "findPetById", - "produces": [ - "application/json", - "application/xml", - "text/xml", - "text/html" - ], - "parameters": [ - { - "name": "id", - "in": "path", - "description": "ID of pet to fetch", - "required": true, - "type": "integer", - "format": "int64" - } - ], - "responses": { - "200": { - "description": "pet response", - "schema": { - "$ref": "#/definitions/Pet" - } - }, - "default": { - "description": "unexpected error", - "schema": { - "$ref": "#/definitions/ErrorModel" - } - } - } - }, - "delete": { - "description": "deletes a single pet based on the ID supplied", - "operationId": "deletePet", - "parameters": [ - { - "name": "id", - "in": "path", - "description": "ID of pet to delete", - "required": true, - "type": "integer", - "format": "int64" - } - ], - "responses": { - "204": { - "description": "pet deleted" - }, - "default": { - "description": "unexpected error", - "schema": { - "$ref": "#/definitions/ErrorModel" - } - } - } - } - } - }, - "definitions": { - "Pet": { - "type": "object", - "allOf": [ - { - "$ref": "#/definitions/NewPet" - }, - { - "required": [ - "id" - ], - "properties": { - "id": { - "type": "integer", - "format": "int64" - } - } - } - ] - }, - "NewPet": { - "type": "object", - "required": [ - "name" - ], - "properties": { - "name": { - "type": "string" - }, - "tag": { - "type": "string" - } - } - }, - "ErrorModel": { - "type": "object", - "required": [ - "code", - "message" - ], - "properties": { - "code": { - "type": "integer", - "format": "int32" - }, - "message": { - "type": "string" - } - } - } - } -} diff --git a/examples/v2.0/json/petstore.json b/examples/v2.0/json/petstore.json deleted file mode 100644 index 415eb3f9ae..0000000000 --- a/examples/v2.0/json/petstore.json +++ /dev/null @@ -1,153 +0,0 @@ -{ - "swagger": "2.0", - "info": { - "version": "1.0.0", - "title": "Swagger Petstore", - "license": { - "name": "MIT" - } - }, - "host": "petstore.swagger.io", - "basePath": "/v1", - "schemes": [ - "http" - ], - "consumes": [ - "application/json" - ], - "produces": [ - "application/json" - ], - "paths": { - "/pets": { - "get": { - "summary": "List all pets", - "operationId": "listPets", - "tags": [ - "pets" - ], - "parameters": [ - { - "name": "limit", - "in": "query", - "description": "How many items to return at one time (max 100)", - "required": false, - "type": "integer", - "format": "int32" - } - ], - "responses": { - "200": { - "description": "An paged array of pets", - "headers": { - "x-next": { - "type": "string", - "description": "A link to the next page of responses" - } - }, - "schema": { - "$ref": "#/definitions/Pets" - } - }, - "default": { - "description": "unexpected error", - "schema": { - "$ref": "#/definitions/Error" - } - } - } - }, - "post": { - "summary": "Create a pet", - "operationId": "createPets", - "tags": [ - "pets" - ], - "responses": { - "201": { - "description": "Null response" - }, - "default": { - "description": "unexpected error", - "schema": { - "$ref": "#/definitions/Error" - } - } - } - } - }, - "/pets/{petId}": { - "get": { - "summary": "Info for a specific pet", - "operationId": "showPetById", - "tags": [ - "pets" - ], - "parameters": [ - { - "name": "petId", - "in": "path", - "required": true, - "description": "The id of the pet to retrieve", - "type": "string" - } - ], - "responses": { - "200": { - "description": "Expected response to a valid request", - "schema": { - "$ref": "#/definitions/Pets" - } - }, - "default": { - "description": "unexpected error", - "schema": { - "$ref": "#/definitions/Error" - } - } - } - } - } - }, - "definitions": { - "Pet": { - "required": [ - "id", - "name" - ], - "properties": { - "id": { - "type": "integer", - "format": "int64" - }, - "name": { - "type": "string" - }, - "tag": { - "type": "string" - } - } - }, - "Pets": { - "type": "array", - "items": { - "$ref": "#/definitions/Pet" - } - }, - "Error": { - "required": [ - "code", - "message" - ], - "properties": { - "code": { - "type": "integer", - "format": "int32" - }, - "message": { - "type": "string" - } - } - } - } -} \ No newline at end of file diff --git a/examples/v2.0/json/uber.json b/examples/v2.0/json/uber.json deleted file mode 100644 index 957782897d..0000000000 --- a/examples/v2.0/json/uber.json +++ /dev/null @@ -1,370 +0,0 @@ -{ - "swagger": "2.0", - "info": { - "title": "Uber API", - "description": "Move your app forward with the Uber API", - "version": "1.0.0" - }, - "host": "api.uber.com", - "schemes": [ - "https" - ], - "basePath": "/v1", - "produces": [ - "application/json" - ], - "paths": { - "/products": { - "get": { - "summary": "Product Types", - "description": "The Products endpoint returns information about the Uber products offered at a given location. The response includes the display name and other details about each product, and lists the products in the proper display order.", - "parameters": [ - { - "name": "latitude", - "in": "query", - "description": "Latitude component of location.", - "required": true, - "type": "number", - "format": "double" - }, - { - "name": "longitude", - "in": "query", - "description": "Longitude component of location.", - "required": true, - "type": "number", - "format": "double" - } - ], - "tags": [ - "Products" - ], - "responses": { - "200": { - "description": "An array of products", - "schema": { - "type": "array", - "items": { - "$ref": "#/definitions/Product" - } - } - }, - "default": { - "description": "Unexpected error", - "schema": { - "$ref": "#/definitions/Error" - } - } - } - } - }, - "/estimates/price": { - "get": { - "summary": "Price Estimates", - "description": "The Price Estimates endpoint returns an estimated price range for each product offered at a given location. The price estimate is provided as a formatted string with the full price range and the localized currency symbol.

The response also includes low and high estimates, and the [ISO 4217](http://en.wikipedia.org/wiki/ISO_4217) currency code for situations requiring currency conversion. When surge is active for a particular product, its surge_multiplier will be greater than 1, but the price estimate already factors in this multiplier.", - "parameters": [ - { - "name": "start_latitude", - "in": "query", - "description": "Latitude component of start location.", - "required": true, - "type": "number", - "format": "double" - }, - { - "name": "start_longitude", - "in": "query", - "description": "Longitude component of start location.", - "required": true, - "type": "number", - "format": "double" - }, - { - "name": "end_latitude", - "in": "query", - "description": "Latitude component of end location.", - "required": true, - "type": "number", - "format": "double" - }, - { - "name": "end_longitude", - "in": "query", - "description": "Longitude component of end location.", - "required": true, - "type": "number", - "format": "double" - } - ], - "tags": [ - "Estimates" - ], - "responses": { - "200": { - "description": "An array of price estimates by product", - "schema": { - "type": "array", - "items": { - "$ref": "#/definitions/PriceEstimate" - } - } - }, - "default": { - "description": "Unexpected error", - "schema": { - "$ref": "#/definitions/Error" - } - } - } - } - }, - "/estimates/time": { - "get": { - "summary": "Time Estimates", - "description": "The Time Estimates endpoint returns ETAs for all products offered at a given location, with the responses expressed as integers in seconds. We recommend that this endpoint be called every minute to provide the most accurate, up-to-date ETAs.", - "parameters": [ - { - "name": "start_latitude", - "in": "query", - "description": "Latitude component of start location.", - "required": true, - "type": "number", - "format": "double" - }, - { - "name": "start_longitude", - "in": "query", - "description": "Longitude component of start location.", - "required": true, - "type": "number", - "format": "double" - }, - { - "name": "customer_uuid", - "in": "query", - "type": "string", - "format": "uuid", - "description": "Unique customer identifier to be used for experience customization." - }, - { - "name": "product_id", - "in": "query", - "type": "string", - "description": "Unique identifier representing a specific product for a given latitude & longitude." - } - ], - "tags": [ - "Estimates" - ], - "responses": { - "200": { - "description": "An array of products", - "schema": { - "type": "array", - "items": { - "$ref": "#/definitions/Product" - } - } - }, - "default": { - "description": "Unexpected error", - "schema": { - "$ref": "#/definitions/Error" - } - } - } - } - }, - "/me": { - "get": { - "summary": "User Profile", - "description": "The User Profile endpoint returns information about the Uber user that has authorized with the application.", - "tags": [ - "User" - ], - "responses": { - "200": { - "description": "Profile information for a user", - "schema": { - "$ref": "#/definitions/Profile" - } - }, - "default": { - "description": "Unexpected error", - "schema": { - "$ref": "#/definitions/Error" - } - } - } - } - }, - "/history": { - "get": { - "summary": "User Activity", - "description": "The User Activity endpoint returns data about a user's lifetime activity with Uber. The response will include pickup locations and times, dropoff locations and times, the distance of past requests, and information about which products were requested.

The history array in the response will have a maximum length based on the limit parameter. The response value count may exceed limit, therefore subsequent API requests may be necessary.", - "parameters": [ - { - "name": "offset", - "in": "query", - "type": "integer", - "format": "int32", - "description": "Offset the list of returned results by this amount. Default is zero." - }, - { - "name": "limit", - "in": "query", - "type": "integer", - "format": "int32", - "description": "Number of items to retrieve. Default is 5, maximum is 100." - } - ], - "tags": [ - "User" - ], - "responses": { - "200": { - "description": "History information for the given user", - "schema": { - "$ref": "#/definitions/Activities" - } - }, - "default": { - "description": "Unexpected error", - "schema": { - "$ref": "#/definitions/Error" - } - } - } - } - } - }, - "definitions": { - "Product": { - "properties": { - "product_id": { - "type": "string", - "description": "Unique identifier representing a specific product for a given latitude & longitude. For example, uberX in San Francisco will have a different product_id than uberX in Los Angeles." - }, - "description": { - "type": "string", - "description": "Description of product." - }, - "display_name": { - "type": "string", - "description": "Display name of product." - }, - "capacity": { - "type": "string", - "description": "Capacity of product. For example, 4 people." - }, - "image": { - "type": "string", - "description": "Image URL representing the product." - } - } - }, - "PriceEstimate": { - "properties": { - "product_id": { - "type": "string", - "description": "Unique identifier representing a specific product for a given latitude & longitude. For example, uberX in San Francisco will have a different product_id than uberX in Los Angeles" - }, - "currency_code": { - "type": "string", - "description": "[ISO 4217](http://en.wikipedia.org/wiki/ISO_4217) currency code." - }, - "display_name": { - "type": "string", - "description": "Display name of product." - }, - "estimate": { - "type": "string", - "description": "Formatted string of estimate in local currency of the start location. Estimate could be a range, a single number (flat rate) or \"Metered\" for TAXI." - }, - "low_estimate": { - "type": "number", - "description": "Lower bound of the estimated price." - }, - "high_estimate": { - "type": "number", - "description": "Upper bound of the estimated price." - }, - "surge_multiplier": { - "type": "number", - "description": "Expected surge multiplier. Surge is active if surge_multiplier is greater than 1. Price estimate already factors in the surge multiplier." - } - } - }, - "Profile": { - "properties": { - "first_name": { - "type": "string", - "description": "First name of the Uber user." - }, - "last_name": { - "type": "string", - "description": "Last name of the Uber user." - }, - "email": { - "type": "string", - "description": "Email address of the Uber user" - }, - "picture": { - "type": "string", - "description": "Image URL of the Uber user." - }, - "promo_code": { - "type": "string", - "description": "Promo code of the Uber user." - } - } - }, - "Activity": { - "properties": { - "uuid": { - "type": "string", - "description": "Unique identifier for the activity" - } - } - }, - "Activities": { - "properties": { - "offset": { - "type": "integer", - "format": "int32", - "description": "Position in pagination." - }, - "limit": { - "type": "integer", - "format": "int32", - "description": "Number of items to retrieve (100 max)." - }, - "count": { - "type": "integer", - "format": "int32", - "description": "Total number of items available." - }, - "history": { - "type": "array", - "items": { - "$ref": "#/definitions/Activity" - } - } - } - }, - "Error": { - "properties": { - "code": { - "type": "integer", - "format": "int32" - }, - "message": { - "type": "string" - }, - "fields": { - "type": "string" - } - } - } - } -} \ No newline at end of file diff --git a/examples/v2.0/yaml/api-with-examples.yaml b/examples/v2.0/yaml/api-with-examples.yaml deleted file mode 100644 index 2f4a1ccf10..0000000000 --- a/examples/v2.0/yaml/api-with-examples.yaml +++ /dev/null @@ -1,164 +0,0 @@ -swagger: "2.0" -info: - title: Simple API overview - version: v2 -paths: - /: - get: - operationId: listVersionsv2 - summary: List API versions - produces: - - application/json - responses: - "200": - description: |- - 200 300 response - examples: - application/json: |- - { - "versions": [ - { - "status": "CURRENT", - "updated": "2011-01-21T11:33:21Z", - "id": "v2.0", - "links": [ - { - "href": "http://127.0.0.1:8774/v2/", - "rel": "self" - } - ] - }, - { - "status": "EXPERIMENTAL", - "updated": "2013-07-23T11:33:21Z", - "id": "v3.0", - "links": [ - { - "href": "http://127.0.0.1:8774/v3/", - "rel": "self" - } - ] - } - ] - } - "300": - description: |- - 200 300 response - examples: - application/json: |- - { - "versions": [ - { - "status": "CURRENT", - "updated": "2011-01-21T11:33:21Z", - "id": "v2.0", - "links": [ - { - "href": "http://127.0.0.1:8774/v2/", - "rel": "self" - } - ] - }, - { - "status": "EXPERIMENTAL", - "updated": "2013-07-23T11:33:21Z", - "id": "v3.0", - "links": [ - { - "href": "http://127.0.0.1:8774/v3/", - "rel": "self" - } - ] - } - ] - } - /v2: - get: - operationId: getVersionDetailsv2 - summary: Show API version details - produces: - - application/json - responses: - "200": - description: |- - 200 203 response - examples: - application/json: |- - { - "version": { - "status": "CURRENT", - "updated": "2011-01-21T11:33:21Z", - "media-types": [ - { - "base": "application/xml", - "type": "application/vnd.openstack.compute+xml;version=2" - }, - { - "base": "application/json", - "type": "application/vnd.openstack.compute+json;version=2" - } - ], - "id": "v2.0", - "links": [ - { - "href": "http://127.0.0.1:8774/v2/", - "rel": "self" - }, - { - "href": "http://docs.openstack.org/api/openstack-compute/2/os-compute-devguide-2.pdf", - "type": "application/pdf", - "rel": "describedby" - }, - { - "href": "http://docs.openstack.org/api/openstack-compute/2/wadl/os-compute-2.wadl", - "type": "application/vnd.sun.wadl+xml", - "rel": "describedby" - }, - { - "href": "http://docs.openstack.org/api/openstack-compute/2/wadl/os-compute-2.wadl", - "type": "application/vnd.sun.wadl+xml", - "rel": "describedby" - } - ] - } - } - "203": - description: |- - 200 203 response - examples: - application/json: |- - { - "version": { - "status": "CURRENT", - "updated": "2011-01-21T11:33:21Z", - "media-types": [ - { - "base": "application/xml", - "type": "application/vnd.openstack.compute+xml;version=2" - }, - { - "base": "application/json", - "type": "application/vnd.openstack.compute+json;version=2" - } - ], - "id": "v2.0", - "links": [ - { - "href": "http://23.253.228.211:8774/v2/", - "rel": "self" - }, - { - "href": "http://docs.openstack.org/api/openstack-compute/2/os-compute-devguide-2.pdf", - "type": "application/pdf", - "rel": "describedby" - }, - { - "href": "http://docs.openstack.org/api/openstack-compute/2/wadl/os-compute-2.wadl", - "type": "application/vnd.sun.wadl+xml", - "rel": "describedby" - } - ] - } - } -consumes: -- application/json diff --git a/examples/v2.0/yaml/petstore-expanded.yaml b/examples/v2.0/yaml/petstore-expanded.yaml deleted file mode 100644 index e415dae654..0000000000 --- a/examples/v2.0/yaml/petstore-expanded.yaml +++ /dev/null @@ -1,139 +0,0 @@ -swagger: "2.0" -info: - version: 1.0.0 - title: Swagger Petstore - description: A sample API that uses a petstore as an example to demonstrate features in the swagger-2.0 specification - termsOfService: http://swagger.io/terms/ - contact: - name: Swagger API Team - email: apiteam@swagger.io - url: http://swagger.io - license: - name: Apache 2.0 - url: https://www.apache.org/licenses/LICENSE-2.0.html -host: petstore.swagger.io -basePath: /api -schemes: - - http -consumes: - - application/json -produces: - - application/json -paths: - /pets: - get: - description: | - Returns all pets from the system that the user has access to - operationId: findPets - parameters: - - name: tags - in: query - description: tags to filter by - required: false - type: array - collectionFormat: csv - items: - type: string - - name: limit - in: query - description: maximum number of results to return - required: false - type: integer - format: int32 - responses: - "200": - description: pet response - schema: - type: array - items: - $ref: '#/definitions/Pet' - default: - description: unexpected error - schema: - $ref: '#/definitions/Error' - post: - description: Creates a new pet in the store. Duplicates are allowed - operationId: addPet - parameters: - - name: pet - in: body - description: Pet to add to the store - required: true - schema: - $ref: '#/definitions/NewPet' - responses: - "200": - description: pet response - schema: - $ref: '#/definitions/Pet' - default: - description: unexpected error - schema: - $ref: '#/definitions/Error' - /pets/{id}: - get: - description: Returns a user based on a single ID, if the user does not have access to the pet - operationId: find pet by id - parameters: - - name: id - in: path - description: ID of pet to fetch - required: true - type: integer - format: int64 - responses: - "200": - description: pet response - schema: - $ref: '#/definitions/Pet' - default: - description: unexpected error - schema: - $ref: '#/definitions/Error' - delete: - description: deletes a single pet based on the ID supplied - operationId: deletePet - parameters: - - name: id - in: path - description: ID of pet to delete - required: true - type: integer - format: int64 - responses: - "204": - description: pet deleted - default: - description: unexpected error - schema: - $ref: '#/definitions/Error' -definitions: - Pet: - allOf: - - $ref: '#/definitions/NewPet' - - required: - - id - properties: - id: - type: integer - format: int64 - - NewPet: - required: - - name - properties: - name: - type: string - tag: - type: string - - Error: - required: - - code - - message - properties: - code: - type: integer - format: int32 - message: - type: string diff --git a/examples/v2.0/yaml/petstore-minimal.yaml b/examples/v2.0/yaml/petstore-minimal.yaml deleted file mode 100644 index c3e06e9152..0000000000 --- a/examples/v2.0/yaml/petstore-minimal.yaml +++ /dev/null @@ -1,47 +0,0 @@ ---- - swagger: "2.0" - info: - version: "1.0.0" - title: "Swagger Petstore" - description: "A sample API that uses a petstore as an example to demonstrate features in the swagger-2.0 specification" - termsOfService: "http://swagger.io/terms/" - contact: - name: "Swagger API Team" - license: - name: "MIT" - host: "petstore.swagger.io" - basePath: "/api" - schemes: - - "http" - consumes: - - "application/json" - produces: - - "application/json" - paths: - /pets: - get: - description: "Returns all pets from the system that the user has access to" - produces: - - "application/json" - responses: - "200": - description: "A list of pets." - schema: - type: "array" - items: - $ref: "#/definitions/Pet" - definitions: - Pet: - type: "object" - required: - - "id" - - "name" - properties: - id: - type: "integer" - format: "int64" - name: - type: "string" - tag: - type: "string" - diff --git a/examples/v2.0/yaml/petstore-separate/common/Error.yaml b/examples/v2.0/yaml/petstore-separate/common/Error.yaml deleted file mode 100644 index 2d87b744fb..0000000000 --- a/examples/v2.0/yaml/petstore-separate/common/Error.yaml +++ /dev/null @@ -1,10 +0,0 @@ -type: object -required: - - code - - message -properties: - code: - type: integer - format: int32 - message: - type: string diff --git a/examples/v2.0/yaml/petstore-separate/spec/NewPet.yaml b/examples/v2.0/yaml/petstore-separate/spec/NewPet.yaml deleted file mode 100644 index 35e67449c5..0000000000 --- a/examples/v2.0/yaml/petstore-separate/spec/NewPet.yaml +++ /dev/null @@ -1,9 +0,0 @@ -type: object -allOf: - - $ref: 'Pet.yaml' - - required: - - name - properties: - description: - type: integer - format: int64 diff --git a/examples/v2.0/yaml/petstore-separate/spec/Pet.yaml b/examples/v2.0/yaml/petstore-separate/spec/Pet.yaml deleted file mode 100644 index bb113196f1..0000000000 --- a/examples/v2.0/yaml/petstore-separate/spec/Pet.yaml +++ /dev/null @@ -1,12 +0,0 @@ -type: object -required: - - id - - name -properties: - id: - type: integer - format: int64 - name: - type: string - tag: - type: string diff --git a/examples/v2.0/yaml/petstore-separate/spec/parameters.yaml b/examples/v2.0/yaml/petstore-separate/spec/parameters.yaml deleted file mode 100644 index 18736aebd0..0000000000 --- a/examples/v2.0/yaml/petstore-separate/spec/parameters.yaml +++ /dev/null @@ -1,16 +0,0 @@ -tagsParam: - name: tags - in: query - description: tags to filter by - required: false - type: array - collectionFormat: csv - items: - type: string -limitsParam: - name: limit - in: query - description: maximum number of results to return - required: false - type: integer - format: int32 diff --git a/examples/v2.0/yaml/petstore-separate/spec/swagger.yaml b/examples/v2.0/yaml/petstore-separate/spec/swagger.yaml deleted file mode 100644 index b937b5022a..0000000000 --- a/examples/v2.0/yaml/petstore-separate/spec/swagger.yaml +++ /dev/null @@ -1,100 +0,0 @@ -swagger: "2.0" -info: - version: 1.0.0 - title: Swagger Petstore - description: A sample API that uses a petstore as an example to demonstrate features in the swagger-2.0 specification - termsOfService: http://swagger.io/terms/ - contact: - name: Swagger API Team - email: apiteam@swagger.io - url: http://swagger.io - license: - name: Apache 2.0 - url: https://www.apache.org/licenses/LICENSE-2.0.html -host: petstore.swagger.io -basePath: /api -schemes: - - http -consumes: - - application/json -produces: - - application/json -paths: - /pets: - get: - description: | - Returns all pets from the system that the user has access to - Nam sed condimentum est. Maecenas tempor sagittis sapien, nec rhoncus sem sagittis sit amet. Aenean at gravida augue, ac iaculis sem. Curabitur odio lorem, ornare eget elementum nec, cursus id lectus. Duis mi turpis, pulvinar ac eros ac, tincidunt varius justo. In hac habitasse platea dictumst. Integer at adipiscing ante, a sagittis ligula. Aenean pharetra tempor ante molestie imperdiet. Vivamus id aliquam diam. Cras quis velit non tortor eleifend sagittis. Praesent at enim pharetra urna volutpat venenatis eget eget mauris. In eleifend fermentum facilisis. Praesent enim enim, gravida ac sodales sed, placerat id erat. Suspendisse lacus dolor, consectetur non augue vel, vehicula interdum libero. Morbi euismod sagittis libero sed lacinia. - - Sed tempus felis lobortis leo pulvinar rutrum. Nam mattis velit nisl, eu condimentum ligula luctus nec. Phasellus semper velit eget aliquet faucibus. In a mattis elit. Phasellus vel urna viverra, condimentum lorem id, rhoncus nibh. Ut pellentesque posuere elementum. Sed a varius odio. Morbi rhoncus ligula libero, vel eleifend nunc tristique vitae. Fusce et sem dui. Aenean nec scelerisque tortor. Fusce malesuada accumsan magna vel tempus. Quisque mollis felis eu dolor tristique, sit amet auctor felis gravida. Sed libero lorem, molestie sed nisl in, accumsan tempor nisi. Fusce sollicitudin massa ut lacinia mattis. Sed vel eleifend lorem. Pellentesque vitae felis pretium, pulvinar elit eu, euismod sapien. - operationId: findPets - parameters: - - $ref: 'parameters.yaml#/tagsParam' - - $ref: 'parameters.yaml#/limitsParam' - responses: - "200": - description: pet response - schema: - type: array - items: - $ref: 'Pet.yaml' - default: - description: unexpected error - schema: - $ref: '../common/Error.yaml' - post: - description: Creates a new pet in the store. Duplicates are allowed - operationId: addPet - parameters: - - name: pet - in: body - description: Pet to add to the store - required: true - schema: - $ref: 'NewPet.yaml' - responses: - "200": - description: pet response - schema: - $ref: 'Pet.yaml' - default: - description: unexpected error - schema: - $ref: '../common/Error.yaml' - /pets/{id}: - get: - description: Returns a user based on a single ID, if the user does not have access to the pet - operationId: find pet by id - parameters: - - name: id - in: path - description: ID of pet to fetch - required: true - type: integer - format: int64 - responses: - "200": - description: pet response - schema: - $ref: 'Pet.yaml' - default: - description: unexpected error - schema: - $ref: '../common/Error.yaml' - delete: - description: deletes a single pet based on the ID supplied - operationId: deletePet - parameters: - - name: id - in: path - description: ID of pet to delete - required: true - type: integer - format: int64 - responses: - "204": - description: pet deleted - default: - description: unexpected error - schema: - $ref: '../common/Error.yaml' diff --git a/examples/v2.0/yaml/petstore-simple.yaml b/examples/v2.0/yaml/petstore-simple.yaml deleted file mode 100644 index d5fa07b428..0000000000 --- a/examples/v2.0/yaml/petstore-simple.yaml +++ /dev/null @@ -1,157 +0,0 @@ ---- - swagger: "2.0" - info: - version: "1.0.0" - title: "Swagger Petstore" - description: "A sample API that uses a petstore as an example to demonstrate features in the swagger-2.0 specification" - termsOfService: "http://swagger.io/terms/" - contact: - name: "Swagger API Team" - license: - name: "MIT" - host: "petstore.swagger.io" - basePath: "/api" - schemes: - - "http" - consumes: - - "application/json" - produces: - - "application/json" - paths: - /pets: - get: - description: "Returns all pets from the system that the user has access to" - operationId: "findPets" - produces: - - "application/json" - - "application/xml" - - "text/xml" - - "text/html" - parameters: - - - name: "tags" - in: "query" - description: "tags to filter by" - required: false - type: "array" - items: - type: "string" - collectionFormat: "csv" - - - name: "limit" - in: "query" - description: "maximum number of results to return" - required: false - type: "integer" - format: "int32" - responses: - "200": - description: "pet response" - schema: - type: "array" - items: - $ref: "#/definitions/Pet" - default: - description: "unexpected error" - schema: - $ref: "#/definitions/ErrorModel" - post: - description: "Creates a new pet in the store. Duplicates are allowed" - operationId: "addPet" - produces: - - "application/json" - parameters: - - - name: "pet" - in: "body" - description: "Pet to add to the store" - required: true - schema: - $ref: "#/definitions/NewPet" - responses: - "200": - description: "pet response" - schema: - $ref: "#/definitions/Pet" - default: - description: "unexpected error" - schema: - $ref: "#/definitions/ErrorModel" - /pets/{id}: - get: - description: "Returns a user based on a single ID, if the user does not have access to the pet" - operationId: "findPetById" - produces: - - "application/json" - - "application/xml" - - "text/xml" - - "text/html" - parameters: - - - name: "id" - in: "path" - description: "ID of pet to fetch" - required: true - type: "integer" - format: "int64" - responses: - "200": - description: "pet response" - schema: - $ref: "#/definitions/Pet" - default: - description: "unexpected error" - schema: - $ref: "#/definitions/ErrorModel" - delete: - description: "deletes a single pet based on the ID supplied" - operationId: "deletePet" - parameters: - - - name: "id" - in: "path" - description: "ID of pet to delete" - required: true - type: "integer" - format: "int64" - responses: - "204": - description: "pet deleted" - default: - description: "unexpected error" - schema: - $ref: "#/definitions/ErrorModel" - definitions: - Pet: - type: "object" - allOf: - - - $ref: "#/definitions/NewPet" - - - required: - - "id" - properties: - id: - type: "integer" - format: "int64" - NewPet: - type: "object" - required: - - "name" - properties: - name: - type: "string" - tag: - type: "string" - ErrorModel: - type: "object" - required: - - "code" - - "message" - properties: - code: - type: "integer" - format: "int32" - message: - type: "string" - diff --git a/examples/v2.0/yaml/petstore-with-external-docs.yaml b/examples/v2.0/yaml/petstore-with-external-docs.yaml deleted file mode 100644 index 792864fca0..0000000000 --- a/examples/v2.0/yaml/petstore-with-external-docs.yaml +++ /dev/null @@ -1,166 +0,0 @@ ---- - swagger: "2.0" - info: - version: "1.0.0" - title: "Swagger Petstore" - description: "A sample API that uses a petstore as an example to demonstrate features in the swagger-2.0 specification" - termsOfService: "http://swagger.io/terms/" - contact: - name: "Swagger API Team" - email: "apiteam@swagger.io" - url: "http://swagger.io" - license: - name: "Apache 2.0" - url: "https://www.apache.org/licenses/LICENSE-2.0.html" - externalDocs: - description: "find more info here" - url: "https://swagger.io/about" - host: "petstore.swagger.io" - basePath: "/api" - schemes: - - "http" - consumes: - - "application/json" - produces: - - "application/json" - paths: - /pets: - get: - description: "Returns all pets from the system that the user has access to" - operationId: "findPets" - externalDocs: - description: "find more info here" - url: "https://swagger.io/about" - produces: - - "application/json" - - "application/xml" - - "text/xml" - - "text/html" - parameters: - - - name: "tags" - in: "query" - description: "tags to filter by" - required: false - type: "array" - items: - type: "string" - collectionFormat: "csv" - - - name: "limit" - in: "query" - description: "maximum number of results to return" - required: false - type: "integer" - format: "int32" - responses: - "200": - description: "pet response" - schema: - type: "array" - items: - $ref: "#/definitions/Pet" - default: - description: "unexpected error" - schema: - $ref: "#/definitions/ErrorModel" - post: - description: "Creates a new pet in the store. Duplicates are allowed" - operationId: "addPet" - produces: - - "application/json" - parameters: - - - name: "pet" - in: "body" - description: "Pet to add to the store" - required: true - schema: - $ref: "#/definitions/NewPet" - responses: - "200": - description: "pet response" - schema: - $ref: "#/definitions/Pet" - default: - description: "unexpected error" - schema: - $ref: "#/definitions/ErrorModel" - /pets/{id}: - get: - description: "Returns a user based on a single ID, if the user does not have access to the pet" - operationId: "findPetById" - produces: - - "application/json" - - "application/xml" - - "text/xml" - - "text/html" - parameters: - - - name: "id" - in: "path" - description: "ID of pet to fetch" - required: true - type: "integer" - format: "int64" - responses: - "200": - description: "pet response" - schema: - $ref: "#/definitions/Pet" - default: - description: "unexpected error" - schema: - $ref: "#/definitions/ErrorModel" - delete: - description: "deletes a single pet based on the ID supplied" - operationId: "deletePet" - parameters: - - - name: "id" - in: "path" - description: "ID of pet to delete" - required: true - type: "integer" - format: "int64" - responses: - "204": - description: "pet deleted" - default: - description: "unexpected error" - schema: - $ref: "#/definitions/ErrorModel" - definitions: - Pet: - type: "object" - allOf: - - - $ref: "#/definitions/NewPet" - - - required: - - "id" - properties: - id: - type: "integer" - format: "int64" - NewPet: - type: "object" - required: - - "name" - properties: - name: - type: "string" - tag: - type: "string" - ErrorModel: - type: "object" - required: - - "code" - - "message" - properties: - code: - type: "integer" - format: "int32" - message: - type: "string" - diff --git a/examples/v2.0/yaml/petstore.yaml b/examples/v2.0/yaml/petstore.yaml deleted file mode 100644 index 4003794e83..0000000000 --- a/examples/v2.0/yaml/petstore.yaml +++ /dev/null @@ -1,101 +0,0 @@ -swagger: "2.0" -info: - version: 1.0.0 - title: Swagger Petstore - license: - name: MIT -host: petstore.swagger.io -basePath: /v1 -schemes: - - http -consumes: - - application/json -produces: - - application/json -paths: - /pets: - get: - summary: List all pets - operationId: listPets - tags: - - pets - parameters: - - name: limit - in: query - description: How many items to return at one time (max 100) - required: false - type: integer - format: int32 - responses: - "200": - description: A paged array of pets - headers: - x-next: - type: string - description: A link to the next page of responses - schema: - $ref: '#/definitions/Pets' - default: - description: unexpected error - schema: - $ref: '#/definitions/Error' - post: - summary: Create a pet - operationId: createPets - tags: - - pets - responses: - "201": - description: Null response - default: - description: unexpected error - schema: - $ref: '#/definitions/Error' - /pets/{petId}: - get: - summary: Info for a specific pet - operationId: showPetById - tags: - - pets - parameters: - - name: petId - in: path - required: true - description: The id of the pet to retrieve - type: string - responses: - "200": - description: Expected response to a valid request - schema: - $ref: '#/definitions/Pets' - default: - description: unexpected error - schema: - $ref: '#/definitions/Error' -definitions: - Pet: - required: - - id - - name - properties: - id: - type: integer - format: int64 - name: - type: string - tag: - type: string - Pets: - type: array - items: - $ref: '#/definitions/Pet' - Error: - required: - - code - - message - properties: - code: - type: integer - format: int32 - message: - type: string diff --git a/examples/v2.0/yaml/uber.yaml b/examples/v2.0/yaml/uber.yaml deleted file mode 100644 index 12c14b08aa..0000000000 --- a/examples/v2.0/yaml/uber.yaml +++ /dev/null @@ -1,273 +0,0 @@ -# this is an example of the Uber API -# as a demonstration of an API spec in YAML -swagger: "2.0" -info: - title: Uber API - description: Move your app forward with the Uber API - version: "1.0.0" -# the domain of the service -host: api.uber.com -# array of all schemes that your API supports -schemes: - - https -# will be prefixed to all paths -basePath: /v1 -securityDefinitions: - apikey: - type: apiKey - name: server_token - in: query -produces: - - application/json -paths: - /products: - get: - summary: Product Types - description: The Products endpoint returns information about the Uber products offered at a given location. The response includes the display name and other details about each product, and lists the products in the proper display order. - parameters: - - name: latitude - in: query - description: Latitude component of location. - required: true - type: number - format: double - - name: longitude - in: query - description: Longitude component of location. - required: true - type: number - format: double - security: - - apikey: [] - tags: - - Products - responses: - "200": - description: An array of products - schema: - type: array - items: - $ref: '#/definitions/Product' - default: - description: Unexpected error - schema: - $ref: '#/definitions/Error' - /estimates/price: - get: - summary: Price Estimates - description: The Price Estimates endpoint returns an estimated price range for each product offered at a given location. The price estimate is provided as a formatted string with the full price range and the localized currency symbol.

The response also includes low and high estimates, and the [ISO 4217](http://en.wikipedia.org/wiki/ISO_4217) currency code for situations requiring currency conversion. When surge is active for a particular product, its surge_multiplier will be greater than 1, but the price estimate already factors in this multiplier. - parameters: - - name: start_latitude - in: query - description: Latitude component of start location. - required: true - type: number - format: double - - name: start_longitude - in: query - description: Longitude component of start location. - required: true - type: number - format: double - - name: end_latitude - in: query - description: Latitude component of end location. - required: true - type: number - format: double - - name: end_longitude - in: query - description: Longitude component of end location. - required: true - type: number - format: double - tags: - - Estimates - responses: - "200": - description: An array of price estimates by product - schema: - type: array - items: - $ref: '#/definitions/PriceEstimate' - default: - description: Unexpected error - schema: - $ref: '#/definitions/Error' - /estimates/time: - get: - summary: Time Estimates - description: The Time Estimates endpoint returns ETAs for all products offered at a given location, with the responses expressed as integers in seconds. We recommend that this endpoint be called every minute to provide the most accurate, up-to-date ETAs. - parameters: - - name: start_latitude - in: query - description: Latitude component of start location. - required: true - type: number - format: double - - name: start_longitude - in: query - description: Longitude component of start location. - required: true - type: number - format: double - - name: customer_uuid - in: query - type: string - format: uuid - description: Unique customer identifier to be used for experience customization. - - name: product_id - in: query - type: string - description: Unique identifier representing a specific product for a given latitude & longitude. - tags: - - Estimates - responses: - "200": - description: An array of products - schema: - type: array - items: - $ref: '#/definitions/Product' - default: - description: Unexpected error - schema: - $ref: '#/definitions/Error' - /me: - get: - summary: User Profile - description: The User Profile endpoint returns information about the Uber user that has authorized with the application. - tags: - - User - responses: - "200": - description: Profile information for a user - schema: - $ref: '#/definitions/Profile' - default: - description: Unexpected error - schema: - $ref: '#/definitions/Error' - /history: - get: - summary: User Activity - description: The User Activity endpoint returns data about a user's lifetime activity with Uber. The response will include pickup locations and times, dropoff locations and times, the distance of past requests, and information about which products were requested.

The history array in the response will have a maximum length based on the limit parameter. The response value count may exceed limit, therefore subsequent API requests may be necessary. - parameters: - - name: offset - in: query - type: integer - format: int32 - description: Offset the list of returned results by this amount. Default is zero. - - name: limit - in: query - type: integer - format: int32 - description: Number of items to retrieve. Default is 5, maximum is 100. - tags: - - User - responses: - "200": - description: History information for the given user - schema: - $ref: '#/definitions/Activities' - default: - description: Unexpected error - schema: - $ref: '#/definitions/Error' -definitions: - Product: - properties: - product_id: - type: string - description: Unique identifier representing a specific product for a given latitude & longitude. For example, uberX in San Francisco will have a different product_id than uberX in Los Angeles. - description: - type: string - description: Description of product. - display_name: - type: string - description: Display name of product. - capacity: - type: integer - description: Capacity of product. For example, 4 people. - image: - type: string - description: Image URL representing the product. - ProductList: - properties: - products: - description: Contains the list of products - type: array - items: - $ref: "#/definitions/Product" - PriceEstimate: - properties: - product_id: - type: string - description: Unique identifier representing a specific product for a given latitude & longitude. For example, uberX in San Francisco will have a different product_id than uberX in Los Angeles - currency_code: - type: string - description: "[ISO 4217](http://en.wikipedia.org/wiki/ISO_4217) currency code." - display_name: - type: string - description: Display name of product. - estimate: - type: string - description: Formatted string of estimate in local currency of the start location. Estimate could be a range, a single number (flat rate) or "Metered" for TAXI. - low_estimate: - type: number - description: Lower bound of the estimated price. - high_estimate: - type: number - description: Upper bound of the estimated price. - surge_multiplier: - type: number - description: Expected surge multiplier. Surge is active if surge_multiplier is greater than 1. Price estimate already factors in the surge multiplier. - Profile: - properties: - first_name: - type: string - description: First name of the Uber user. - last_name: - type: string - description: Last name of the Uber user. - email: - type: string - description: Email address of the Uber user - picture: - type: string - description: Image URL of the Uber user. - promo_code: - type: string - description: Promo code of the Uber user. - Activity: - properties: - uuid: - type: string - description: Unique identifier for the activity - Activities: - properties: - offset: - type: integer - format: int32 - description: Position in pagination. - limit: - type: integer - format: int32 - description: Number of items to retrieve (100 max). - count: - type: integer - format: int32 - description: Total number of items available. - history: - type: array - items: - $ref: '#/definitions/Activity' - Error: - properties: - code: - type: integer - format: int32 - message: - type: string - fields: - type: string diff --git a/fixtures/v1.2/helloworld/server/README.md b/fixtures/v1.2/helloworld/server/README.md deleted file mode 100644 index bd351e2c1c..0000000000 --- a/fixtures/v1.2/helloworld/server/README.md +++ /dev/null @@ -1,20 +0,0 @@ -# All-in-one Static Hello World Sample - -This sample project provides an all-one-one package demo for the Hello World sample described in the [wiki](https://github.com/swagger-api/swagger-spec/wiki/Hello-World-Sample). - -## Requirements - -This samples requires Java 5 or above and [Maven](http://maven.apache.org) installed. - -## Run the sample - -In your favorite command-line, run: - -``` -mvn jetty:run -``` - -Then in your favorite web browser, open: -``` -http://localhost:8000 -``` diff --git a/fixtures/v1.2/helloworld/server/pom.xml b/fixtures/v1.2/helloworld/server/pom.xml deleted file mode 100644 index 3a2c61c671..0000000000 --- a/fixtures/v1.2/helloworld/server/pom.xml +++ /dev/null @@ -1,111 +0,0 @@ - - 4.0.0 - io.swagger - swagger-demo - jar - swagger-demo - 1.0.1-SNAPSHOT - - 2.2.0 - - - - src/main/scala - src/test/scala - - - net.alchim31.maven - scala-maven-plugin - ${maven-plugin.version} - - - - compile - testCompile - - - - - - -Xms64m - -Xmx1024m - - - - - maven-surefire-plugin - - once - false - - - - maven-dependency-plugin - - - package - - copy-dependencies - - - ${project.build.directory}/lib - - - - - - org.mortbay.jetty - jetty-maven-plugin - ${jetty-version} - - - / - - - - 8000 - 60000 - 8443 - - - - - - start-jetty - pre-integration-test - - run - - - 0 - true - - - - stop-jetty - post-integration-test - - stop - - - - - - - - - sonatype-snapshots - https://oss.sonatype.org/content/repositories/snapshots - - - sonatype-releases - https://oss.sonatype.org/content/repositories/releases - - - - 3.1.0 - 7.6.0.v20120127 - - - diff --git a/fixtures/v1.2/helloworld/server/src/main/webapp/api-docs b/fixtures/v1.2/helloworld/server/src/main/webapp/api-docs deleted file mode 100644 index 6f2f3cb95b..0000000000 --- a/fixtures/v1.2/helloworld/server/src/main/webapp/api-docs +++ /dev/null @@ -1,9 +0,0 @@ -{ - "swaggerVersion": "1.2", - "apis": [ - { - "path": "http://localhost:8000/listings/greetings", - "description": "Generating greetings in our application." - } - ] -} diff --git a/fixtures/v1.2/helloworld/server/src/main/webapp/css/highlight.default.css b/fixtures/v1.2/helloworld/server/src/main/webapp/css/highlight.default.css deleted file mode 100644 index e417fc1799..0000000000 --- a/fixtures/v1.2/helloworld/server/src/main/webapp/css/highlight.default.css +++ /dev/null @@ -1,135 +0,0 @@ -/* - -Original style from softwaremaniacs.org (c) Ivan Sagalaev - -*/ - -pre code { - display: block; padding: 0.5em; - background: #F0F0F0; -} - -pre code, -pre .subst, -pre .tag .title, -pre .lisp .title, -pre .clojure .built_in, -pre .nginx .title { - color: black; -} - -pre .string, -pre .title, -pre .constant, -pre .parent, -pre .tag .value, -pre .rules .value, -pre .rules .value .number, -pre .preprocessor, -pre .ruby .symbol, -pre .ruby .symbol .string, -pre .aggregate, -pre .template_tag, -pre .django .variable, -pre .smalltalk .class, -pre .addition, -pre .flow, -pre .stream, -pre .bash .variable, -pre .apache .tag, -pre .apache .cbracket, -pre .tex .command, -pre .tex .special, -pre .erlang_repl .function_or_atom, -pre .markdown .header { - color: #800; -} - -pre .comment, -pre .annotation, -pre .template_comment, -pre .diff .header, -pre .chunk, -pre .markdown .blockquote { - color: #888; -} - -pre .number, -pre .date, -pre .regexp, -pre .literal, -pre .smalltalk .symbol, -pre .smalltalk .char, -pre .go .constant, -pre .change, -pre .markdown .bullet, -pre .markdown .link_url { - color: #080; -} - -pre .label, -pre .javadoc, -pre .ruby .string, -pre .decorator, -pre .filter .argument, -pre .localvars, -pre .array, -pre .attr_selector, -pre .important, -pre .pseudo, -pre .pi, -pre .doctype, -pre .deletion, -pre .envvar, -pre .shebang, -pre .apache .sqbracket, -pre .nginx .built_in, -pre .tex .formula, -pre .erlang_repl .reserved, -pre .prompt, -pre .markdown .link_label, -pre .vhdl .attribute, -pre .clojure .attribute, -pre .coffeescript .property { - color: #88F -} - -pre .keyword, -pre .id, -pre .phpdoc, -pre .title, -pre .built_in, -pre .aggregate, -pre .css .tag, -pre .javadoctag, -pre .phpdoc, -pre .yardoctag, -pre .smalltalk .class, -pre .winutils, -pre .bash .variable, -pre .apache .tag, -pre .go .typename, -pre .tex .command, -pre .markdown .strong, -pre .request, -pre .status { - font-weight: bold; -} - -pre .markdown .emphasis { - font-style: italic; -} - -pre .nginx .built_in { - font-weight: normal; -} - -pre .coffeescript .javascript, -pre .javascript .xml, -pre .tex .formula, -pre .xml .javascript, -pre .xml .vbscript, -pre .xml .css, -pre .xml .cdata { - opacity: 0.5; -} diff --git a/fixtures/v1.2/helloworld/server/src/main/webapp/css/screen.css b/fixtures/v1.2/helloworld/server/src/main/webapp/css/screen.css deleted file mode 100644 index 1627ecd0d3..0000000000 --- a/fixtures/v1.2/helloworld/server/src/main/webapp/css/screen.css +++ /dev/null @@ -1,1070 +0,0 @@ -/* http://meyerweb.com/eric/tools/css/reset/ v2.0 | 20110126 */ -html, -body, -div, -span, -applet, -object, -iframe, -h1, -h2, -h3, -h4, -h5, -h6, -p, -blockquote, -pre, -a, -abbr, -acronym, -address, -big, -cite, -code, -del, -dfn, -em, -img, -ins, -kbd, -q, -s, -samp, -small, -strike, -strong, -sub, -sup, -tt, -var, -b, -u, -i, -center, -dl, -dt, -dd, -ol, -ul, -li, -fieldset, -form, -label, -legend, -table, -caption, -tbody, -tfoot, -thead, -tr, -th, -td, -article, -aside, -canvas, -details, -embed, -figure, -figcaption, -footer, -header, -hgroup, -menu, -nav, -output, -ruby, -section, -summary, -time, -mark, -audio, -video { - margin: 0; - padding: 0; - border: 0; - font-size: 100%; - font: inherit; - vertical-align: baseline; -} -/* HTML5 display-role reset for older browsers */ -article, -aside, -details, -figcaption, -figure, -footer, -header, -hgroup, -menu, -nav, -section { - display: block; -} -body { - line-height: 1; -} -ol, -ul { - list-style: none; -} -blockquote, -q { - quotes: none; -} -blockquote:before, -blockquote:after, -q:before, -q:after { - content: ''; - content: none; -} -table { - border-collapse: collapse; - border-spacing: 0; -} -.swagger-ui-wrap { - line-height: 1; - font-family: "Droid Sans", sans-serif; - max-width: 960px; - margin-left: auto; - margin-right: auto; -} -.swagger-ui-wrap b, -.swagger-ui-wrap strong { - font-family: "Droid Sans", sans-serif; - font-weight: bold; -} -.swagger-ui-wrap q, -.swagger-ui-wrap blockquote { - quotes: none; -} -.swagger-ui-wrap p { - line-height: 1.4em; - padding: 0 0 10px; - color: #333333; -} -.swagger-ui-wrap q:before, -.swagger-ui-wrap q:after, -.swagger-ui-wrap blockquote:before, -.swagger-ui-wrap blockquote:after { - content: none; -} -.swagger-ui-wrap .heading_with_menu h1, -.swagger-ui-wrap .heading_with_menu h2, -.swagger-ui-wrap .heading_with_menu h3, -.swagger-ui-wrap .heading_with_menu h4, -.swagger-ui-wrap .heading_with_menu h5, -.swagger-ui-wrap .heading_with_menu h6 { - display: block; - clear: none; - float: left; - -moz-box-sizing: border-box; - -webkit-box-sizing: border-box; - -ms-box-sizing: border-box; - box-sizing: border-box; - width: 60%; -} -.swagger-ui-wrap table { - border-collapse: collapse; - border-spacing: 0; -} -.swagger-ui-wrap table thead tr th { - padding: 5px; - font-size: 0.9em; - color: #666666; - border-bottom: 1px solid #999999; -} -.swagger-ui-wrap table tbody tr:last-child td { - border-bottom: none; -} -.swagger-ui-wrap table tbody tr.offset { - background-color: #f0f0f0; -} -.swagger-ui-wrap table tbody tr td { - padding: 6px; - font-size: 0.9em; - border-bottom: 1px solid #cccccc; - vertical-align: top; - line-height: 1.3em; -} -.swagger-ui-wrap ol { - margin: 0px 0 10px; - padding: 0 0 0 18px; - list-style-type: decimal; -} -.swagger-ui-wrap ol li { - padding: 5px 0px; - font-size: 0.9em; - color: #333333; -} -.swagger-ui-wrap ol, -.swagger-ui-wrap ul { - list-style: none; -} -.swagger-ui-wrap h1 a, -.swagger-ui-wrap h2 a, -.swagger-ui-wrap h3 a, -.swagger-ui-wrap h4 a, -.swagger-ui-wrap h5 a, -.swagger-ui-wrap h6 a { - text-decoration: none; -} -.swagger-ui-wrap h1 a:hover, -.swagger-ui-wrap h2 a:hover, -.swagger-ui-wrap h3 a:hover, -.swagger-ui-wrap h4 a:hover, -.swagger-ui-wrap h5 a:hover, -.swagger-ui-wrap h6 a:hover { - text-decoration: underline; -} -.swagger-ui-wrap h1 span.divider, -.swagger-ui-wrap h2 span.divider, -.swagger-ui-wrap h3 span.divider, -.swagger-ui-wrap h4 span.divider, -.swagger-ui-wrap h5 span.divider, -.swagger-ui-wrap h6 span.divider { - color: #aaaaaa; -} -.swagger-ui-wrap a { - color: #547f00; -} -.swagger-ui-wrap a img { - border: none; -} -.swagger-ui-wrap article, -.swagger-ui-wrap aside, -.swagger-ui-wrap details, -.swagger-ui-wrap figcaption, -.swagger-ui-wrap figure, -.swagger-ui-wrap footer, -.swagger-ui-wrap header, -.swagger-ui-wrap hgroup, -.swagger-ui-wrap menu, -.swagger-ui-wrap nav, -.swagger-ui-wrap section, -.swagger-ui-wrap summary { - display: block; -} -.swagger-ui-wrap pre { - font-family: "Anonymous Pro", "Menlo", "Consolas", "Bitstream Vera Sans Mono", "Courier New", monospace; - background-color: #fcf6db; - border: 1px solid #e5e0c6; - padding: 10px; -} -.swagger-ui-wrap pre code { - line-height: 1.6em; - background: none; -} -.swagger-ui-wrap .content > .content-type > div > label { - clear: both; - display: block; - color: #0F6AB4; - font-size: 1.1em; - margin: 0; - padding: 15px 0 5px; -} -.swagger-ui-wrap .content pre { - font-size: 12px; - margin-top: 5px; - padding: 5px; -} -.swagger-ui-wrap .icon-btn { - cursor: pointer; -} -.swagger-ui-wrap .info_title { - padding-bottom: 10px; - font-weight: bold; - font-size: 25px; -} -.swagger-ui-wrap p.big, -.swagger-ui-wrap div.big p { - font-size: 1em; - margin-bottom: 10px; -} -.swagger-ui-wrap form.fullwidth ol li.string input, -.swagger-ui-wrap form.fullwidth ol li.url input, -.swagger-ui-wrap form.fullwidth ol li.text textarea, -.swagger-ui-wrap form.fullwidth ol li.numeric input { - width: 500px !important; -} -.swagger-ui-wrap .info_license { - padding-bottom: 5px; -} -.swagger-ui-wrap .info_tos { - padding-bottom: 5px; -} -.swagger-ui-wrap .message-fail { - color: #cc0000; -} -.swagger-ui-wrap .info_contact { - padding-bottom: 5px; -} -.swagger-ui-wrap .info_description { - padding-bottom: 10px; - font-size: 15px; -} -.swagger-ui-wrap .markdown ol li, -.swagger-ui-wrap .markdown ul li { - padding: 3px 0px; - line-height: 1.4em; - color: #333333; -} -.swagger-ui-wrap form.formtastic fieldset.inputs ol li.string input, -.swagger-ui-wrap form.formtastic fieldset.inputs ol li.url input, -.swagger-ui-wrap form.formtastic fieldset.inputs ol li.numeric input { - display: block; - padding: 4px; - width: auto; - clear: both; -} -.swagger-ui-wrap form.formtastic fieldset.inputs ol li.string input.title, -.swagger-ui-wrap form.formtastic fieldset.inputs ol li.url input.title, -.swagger-ui-wrap form.formtastic fieldset.inputs ol li.numeric input.title { - font-size: 1.3em; -} -.swagger-ui-wrap table.fullwidth { - width: 100%; -} -.swagger-ui-wrap .model-signature { - font-family: "Droid Sans", sans-serif; - font-size: 1em; - line-height: 1.5em; -} -.swagger-ui-wrap .model-signature .signature-nav a { - text-decoration: none; - color: #AAA; -} -.swagger-ui-wrap .model-signature .signature-nav a:hover { - text-decoration: underline; - color: black; -} -.swagger-ui-wrap .model-signature .signature-nav .selected { - color: black; - text-decoration: none; -} -.swagger-ui-wrap .model-signature .propType { - color: #5555aa; -} -.swagger-ui-wrap .model-signature pre:hover { - background-color: #ffffdd; -} -.swagger-ui-wrap .model-signature pre { - font-size: .85em; - line-height: 1.2em; - overflow: auto; - max-height: 200px; - cursor: pointer; -} -.swagger-ui-wrap .model-signature ul.signature-nav { - display: block; - margin: 0; - padding: 0; -} -.swagger-ui-wrap .model-signature ul.signature-nav li:last-child { - padding-right: 0; - border-right: none; -} -.swagger-ui-wrap .model-signature ul.signature-nav li { - float: left; - margin: 0 5px 5px 0; - padding: 2px 5px 2px 0; - border-right: 1px solid #ddd; -} -.swagger-ui-wrap .model-signature .propOpt { - color: #555; -} -.swagger-ui-wrap .model-signature .snippet small { - font-size: 0.75em; -} -.swagger-ui-wrap .model-signature .propOptKey { - font-style: italic; -} -.swagger-ui-wrap .model-signature .description .strong { - font-weight: bold; - color: #000; - font-size: .9em; -} -.swagger-ui-wrap .model-signature .description div { - font-size: 0.9em; - line-height: 1.5em; - margin-left: 1em; -} -.swagger-ui-wrap .model-signature .description .stronger { - font-weight: bold; - color: #000; -} -.swagger-ui-wrap .model-signature .propName { - font-weight: bold; -} -.swagger-ui-wrap .model-signature .signature-container { - clear: both; -} -.swagger-ui-wrap .body-textarea { - width: 300px; - height: 100px; - border: 1px solid #aaa; -} -.swagger-ui-wrap .markdown p code, -.swagger-ui-wrap .markdown li code { - font-family: "Anonymous Pro", "Menlo", "Consolas", "Bitstream Vera Sans Mono", "Courier New", monospace; - background-color: #f0f0f0; - color: black; - padding: 1px 3px; -} -.swagger-ui-wrap .required { - font-weight: bold; -} -.swagger-ui-wrap input.parameter { - width: 300px; - border: 1px solid #aaa; -} -.swagger-ui-wrap h1 { - color: black; - font-size: 1.5em; - line-height: 1.3em; - padding: 10px 0 10px 0; - font-family: "Droid Sans", sans-serif; - font-weight: bold; -} -.swagger-ui-wrap .heading_with_menu { - float: none; - clear: both; - overflow: hidden; - display: block; -} -.swagger-ui-wrap .heading_with_menu ul { - display: block; - clear: none; - float: right; - -moz-box-sizing: border-box; - -webkit-box-sizing: border-box; - -ms-box-sizing: border-box; - box-sizing: border-box; - margin-top: 10px; -} -.swagger-ui-wrap h2 { - color: black; - font-size: 1.3em; - padding: 10px 0 10px 0; -} -.swagger-ui-wrap h2 a { - color: black; -} -.swagger-ui-wrap h2 span.sub { - font-size: 0.7em; - color: #999999; - font-style: italic; -} -.swagger-ui-wrap h2 span.sub a { - color: #777777; -} -.swagger-ui-wrap span.weak { - color: #666666; -} -.swagger-ui-wrap .message-success { - color: #89BF04; -} -.swagger-ui-wrap caption, -.swagger-ui-wrap th, -.swagger-ui-wrap td { - text-align: left; - font-weight: normal; - vertical-align: middle; -} -.swagger-ui-wrap .code { - font-family: "Anonymous Pro", "Menlo", "Consolas", "Bitstream Vera Sans Mono", "Courier New", monospace; -} -.swagger-ui-wrap form.formtastic fieldset.inputs ol li.text textarea { - font-family: "Droid Sans", sans-serif; - height: 250px; - padding: 4px; - display: block; - clear: both; -} -.swagger-ui-wrap form.formtastic fieldset.inputs ol li.select select { - display: block; - clear: both; -} -.swagger-ui-wrap form.formtastic fieldset.inputs ol li.boolean { - float: none; - clear: both; - overflow: hidden; - display: block; -} -.swagger-ui-wrap form.formtastic fieldset.inputs ol li.boolean label { - display: block; - float: left; - clear: none; - margin: 0; - padding: 0; -} -.swagger-ui-wrap form.formtastic fieldset.inputs ol li.boolean input { - display: block; - float: left; - clear: none; - margin: 0 5px 0 0; -} -.swagger-ui-wrap form.formtastic fieldset.inputs ol li.required label { - color: black; -} -.swagger-ui-wrap form.formtastic fieldset.inputs ol li label { - display: block; - clear: both; - width: auto; - padding: 0 0 3px; - color: #666666; -} -.swagger-ui-wrap form.formtastic fieldset.inputs ol li label abbr { - padding-left: 3px; - color: #888888; -} -.swagger-ui-wrap form.formtastic fieldset.inputs ol li p.inline-hints { - margin-left: 0; - font-style: italic; - font-size: 0.9em; - margin: 0; -} -.swagger-ui-wrap form.formtastic fieldset.buttons { - margin: 0; - padding: 0; -} -.swagger-ui-wrap span.blank, -.swagger-ui-wrap span.empty { - color: #888888; - font-style: italic; -} -.swagger-ui-wrap .markdown h3 { - color: #547f00; -} -.swagger-ui-wrap .markdown h4 { - color: #666666; -} -.swagger-ui-wrap .markdown pre { - font-family: "Anonymous Pro", "Menlo", "Consolas", "Bitstream Vera Sans Mono", "Courier New", monospace; - background-color: #fcf6db; - border: 1px solid #e5e0c6; - padding: 10px; - margin: 0 0 10px 0; -} -.swagger-ui-wrap .markdown pre code { - line-height: 1.6em; -} -.swagger-ui-wrap div.gist { - margin: 20px 0 25px 0 !important; -} -.swagger-ui-wrap ul#resources { - font-family: "Droid Sans", sans-serif; - font-size: 0.9em; -} -.swagger-ui-wrap ul#resources li.resource { - border-bottom: 1px solid #dddddd; -} -.swagger-ui-wrap ul#resources li.resource:hover div.heading h2 a, -.swagger-ui-wrap ul#resources li.resource.active div.heading h2 a { - color: black; -} -.swagger-ui-wrap ul#resources li.resource:hover div.heading ul.options li a, -.swagger-ui-wrap ul#resources li.resource.active div.heading ul.options li a { - color: #555555; -} -.swagger-ui-wrap ul#resources li.resource:last-child { - border-bottom: none; -} -.swagger-ui-wrap ul#resources li.resource div.heading { - border: 1px solid transparent; - float: none; - clear: both; - overflow: hidden; - display: block; -} -.swagger-ui-wrap ul#resources li.resource div.heading ul.options { - overflow: hidden; - padding: 0; - display: block; - clear: none; - float: right; - margin: 14px 10px 0 0; -} -.swagger-ui-wrap ul#resources li.resource div.heading ul.options li { - float: left; - clear: none; - margin: 0; - padding: 2px 10px; - border-right: 1px solid #dddddd; - color: #666666; - font-size: 0.9em; -} -.swagger-ui-wrap ul#resources li.resource div.heading ul.options li a { - color: #aaaaaa; - text-decoration: none; -} -.swagger-ui-wrap ul#resources li.resource div.heading ul.options li a:hover { - text-decoration: underline; - color: black; -} -.swagger-ui-wrap ul#resources li.resource div.heading ul.options li a:hover, -.swagger-ui-wrap ul#resources li.resource div.heading ul.options li a:active, -.swagger-ui-wrap ul#resources li.resource div.heading ul.options li a.active { - text-decoration: underline; -} -.swagger-ui-wrap ul#resources li.resource div.heading ul.options li:first-child, -.swagger-ui-wrap ul#resources li.resource div.heading ul.options li.first { - padding-left: 0; -} -.swagger-ui-wrap ul#resources li.resource div.heading ul.options li:last-child, -.swagger-ui-wrap ul#resources li.resource div.heading ul.options li.last { - padding-right: 0; - border-right: none; -} -.swagger-ui-wrap ul#resources li.resource div.heading ul.options:first-child, -.swagger-ui-wrap ul#resources li.resource div.heading ul.options.first { - padding-left: 0; -} -.swagger-ui-wrap ul#resources li.resource div.heading h2 { - color: #999999; - padding-left: 0; - display: block; - clear: none; - float: left; - font-family: "Droid Sans", sans-serif; - font-weight: bold; -} -.swagger-ui-wrap ul#resources li.resource div.heading h2 a { - color: #999999; -} -.swagger-ui-wrap ul#resources li.resource div.heading h2 a:hover { - color: black; -} -.swagger-ui-wrap ul#resources li.resource ul.endpoints li.endpoint ul.operations li.operation { - float: none; - clear: both; - overflow: hidden; - display: block; - margin: 0 0 10px; - padding: 0; -} -.swagger-ui-wrap ul#resources li.resource ul.endpoints li.endpoint ul.operations li.operation div.heading { - float: none; - clear: both; - overflow: hidden; - display: block; - margin: 0; - padding: 0; -} -.swagger-ui-wrap ul#resources li.resource ul.endpoints li.endpoint ul.operations li.operation div.heading h3 { - display: block; - clear: none; - float: left; - width: auto; - margin: 0; - padding: 0; - line-height: 1.1em; - color: black; -} -.swagger-ui-wrap ul#resources li.resource ul.endpoints li.endpoint ul.operations li.operation div.heading h3 span.path { - padding-left: 10px; -} -.swagger-ui-wrap ul#resources li.resource ul.endpoints li.endpoint ul.operations li.operation div.heading h3 span.path a { - color: black; - text-decoration: none; -} -.swagger-ui-wrap ul#resources li.resource ul.endpoints li.endpoint ul.operations li.operation div.heading h3 span.path a:hover { - text-decoration: underline; -} -.swagger-ui-wrap ul#resources li.resource ul.endpoints li.endpoint ul.operations li.operation div.heading h3 span.http_method a { - text-transform: uppercase; - text-decoration: none; - color: white; - display: inline-block; - width: 50px; - font-size: 0.7em; - text-align: center; - padding: 7px 0 4px; - -moz-border-radius: 2px; - -webkit-border-radius: 2px; - -o-border-radius: 2px; - -ms-border-radius: 2px; - -khtml-border-radius: 2px; - border-radius: 2px; -} -.swagger-ui-wrap ul#resources li.resource ul.endpoints li.endpoint ul.operations li.operation div.heading h3 span { - margin: 0; - padding: 0; -} -.swagger-ui-wrap ul#resources li.resource ul.endpoints li.endpoint ul.operations li.operation div.heading ul.options { - overflow: hidden; - padding: 0; - display: block; - clear: none; - float: right; - margin: 6px 10px 0 0; -} -.swagger-ui-wrap ul#resources li.resource ul.endpoints li.endpoint ul.operations li.operation div.heading ul.options li { - float: left; - clear: none; - margin: 0; - padding: 2px 10px; - font-size: 0.9em; -} -.swagger-ui-wrap ul#resources li.resource ul.endpoints li.endpoint ul.operations li.operation div.heading ul.options li a { - text-decoration: none; -} -.swagger-ui-wrap ul#resources li.resource ul.endpoints li.endpoint ul.operations li.operation div.content { - border-top: none; - padding: 10px; - -moz-border-radius-bottomleft: 6px; - -webkit-border-bottom-left-radius: 6px; - -o-border-bottom-left-radius: 6px; - -ms-border-bottom-left-radius: 6px; - -khtml-border-bottom-left-radius: 6px; - border-bottom-left-radius: 6px; - -moz-border-radius-bottomright: 6px; - -webkit-border-bottom-right-radius: 6px; - -o-border-bottom-right-radius: 6px; - -ms-border-bottom-right-radius: 6px; - -khtml-border-bottom-right-radius: 6px; - border-bottom-right-radius: 6px; - margin: 0 0 20px; -} -.swagger-ui-wrap ul#resources li.resource ul.endpoints li.endpoint ul.operations li.operation div.content h4 { - font-size: 1.1em; - margin: 0; - padding: 15px 0 5px; -} -.swagger-ui-wrap ul#resources li.resource ul.endpoints li.endpoint ul.operations li.operation div.content div.sandbox_header { - float: none; - clear: both; - overflow: hidden; - display: block; -} -.swagger-ui-wrap ul#resources li.resource ul.endpoints li.endpoint ul.operations li.operation div.content div.sandbox_header a { - padding: 4px 0 0 10px; - display: inline-block; - font-size: 0.9em; -} -.swagger-ui-wrap ul#resources li.resource ul.endpoints li.endpoint ul.operations li.operation div.content div.sandbox_header img { - display: block; - clear: none; - float: right; -} -.swagger-ui-wrap ul#resources li.resource ul.endpoints li.endpoint ul.operations li.operation div.content div.sandbox_header input.submit { - display: block; - clear: none; - float: left; - padding: 6px 8px; -} -.swagger-ui-wrap ul#resources li.resource ul.endpoints li.endpoint ul.operations li.operation div.content form input[type='text'].error { - outline: 2px solid black; - outline-color: #cc0000; -} -.swagger-ui-wrap ul#resources li.resource ul.endpoints li.endpoint ul.operations li.operation div.content div.response div.block pre { - font-family: "Anonymous Pro", "Menlo", "Consolas", "Bitstream Vera Sans Mono", "Courier New", monospace; - padding: 10px; - font-size: 0.9em; - max-height: 400px; - overflow-y: auto; -} -.swagger-ui-wrap ul#resources li.resource ul.endpoints li.endpoint ul.operations li.operation.put div.heading { - background-color: #f9f2e9; - border: 1px solid #f0e0ca; -} -.swagger-ui-wrap ul#resources li.resource ul.endpoints li.endpoint ul.operations li.operation.put div.heading h3 span.http_method a { - background-color: #c5862b; -} -.swagger-ui-wrap ul#resources li.resource ul.endpoints li.endpoint ul.operations li.operation.put div.heading ul.options li { - border-right: 1px solid #dddddd; - border-right-color: #f0e0ca; - color: #c5862b; -} -.swagger-ui-wrap ul#resources li.resource ul.endpoints li.endpoint ul.operations li.operation.put div.heading ul.options li a { - color: #c5862b; -} -.swagger-ui-wrap ul#resources li.resource ul.endpoints li.endpoint ul.operations li.operation.put div.content { - background-color: #faf5ee; - border: 1px solid #f0e0ca; -} -.swagger-ui-wrap ul#resources li.resource ul.endpoints li.endpoint ul.operations li.operation.put div.content h4 { - color: #c5862b; -} -.swagger-ui-wrap ul#resources li.resource ul.endpoints li.endpoint ul.operations li.operation.put div.content div.sandbox_header a { - color: #dcb67f; -} -.swagger-ui-wrap ul#resources li.resource ul.endpoints li.endpoint ul.operations li.operation.head div.heading { - background-color: #fcffcd; - border: 1px solid black; - border-color: #ffd20f; -} -.swagger-ui-wrap ul#resources li.resource ul.endpoints li.endpoint ul.operations li.operation.head div.heading h3 span.http_method a { - text-transform: uppercase; - background-color: #ffd20f; -} -.swagger-ui-wrap ul#resources li.resource ul.endpoints li.endpoint ul.operations li.operation.head div.heading ul.options li { - border-right: 1px solid #dddddd; - border-right-color: #ffd20f; - color: #ffd20f; -} -.swagger-ui-wrap ul#resources li.resource ul.endpoints li.endpoint ul.operations li.operation.head div.heading ul.options li a { - color: #ffd20f; -} -.swagger-ui-wrap ul#resources li.resource ul.endpoints li.endpoint ul.operations li.operation.head div.content { - background-color: #fcffcd; - border: 1px solid black; - border-color: #ffd20f; -} -.swagger-ui-wrap ul#resources li.resource ul.endpoints li.endpoint ul.operations li.operation.head div.content h4 { - color: #ffd20f; -} -.swagger-ui-wrap ul#resources li.resource ul.endpoints li.endpoint ul.operations li.operation.head div.content div.sandbox_header a { - color: #6fc992; -} -.swagger-ui-wrap ul#resources li.resource ul.endpoints li.endpoint ul.operations li.operation.delete div.heading { - background-color: #f5e8e8; - border: 1px solid #e8c6c7; -} -.swagger-ui-wrap ul#resources li.resource ul.endpoints li.endpoint ul.operations li.operation.delete div.heading h3 span.http_method a { - text-transform: uppercase; - background-color: #a41e22; -} -.swagger-ui-wrap ul#resources li.resource ul.endpoints li.endpoint ul.operations li.operation.delete div.heading ul.options li { - border-right: 1px solid #dddddd; - border-right-color: #e8c6c7; - color: #a41e22; -} -.swagger-ui-wrap ul#resources li.resource ul.endpoints li.endpoint ul.operations li.operation.delete div.heading ul.options li a { - color: #a41e22; -} -.swagger-ui-wrap ul#resources li.resource ul.endpoints li.endpoint ul.operations li.operation.delete div.content { - background-color: #f7eded; - border: 1px solid #e8c6c7; -} -.swagger-ui-wrap ul#resources li.resource ul.endpoints li.endpoint ul.operations li.operation.delete div.content h4 { - color: #a41e22; -} -.swagger-ui-wrap ul#resources li.resource ul.endpoints li.endpoint ul.operations li.operation.delete div.content div.sandbox_header a { - color: #c8787a; -} -.swagger-ui-wrap ul#resources li.resource ul.endpoints li.endpoint ul.operations li.operation.post div.heading { - background-color: #e7f6ec; - border: 1px solid #c3e8d1; -} -.swagger-ui-wrap ul#resources li.resource ul.endpoints li.endpoint ul.operations li.operation.post div.heading h3 span.http_method a { - background-color: #10a54a; -} -.swagger-ui-wrap ul#resources li.resource ul.endpoints li.endpoint ul.operations li.operation.post div.heading ul.options li { - border-right: 1px solid #dddddd; - border-right-color: #c3e8d1; - color: #10a54a; -} -.swagger-ui-wrap ul#resources li.resource ul.endpoints li.endpoint ul.operations li.operation.post div.heading ul.options li a { - color: #10a54a; -} -.swagger-ui-wrap ul#resources li.resource ul.endpoints li.endpoint ul.operations li.operation.post div.content { - background-color: #ebf7f0; - border: 1px solid #c3e8d1; -} -.swagger-ui-wrap ul#resources li.resource ul.endpoints li.endpoint ul.operations li.operation.post div.content h4 { - color: #10a54a; -} -.swagger-ui-wrap ul#resources li.resource ul.endpoints li.endpoint ul.operations li.operation.post div.content div.sandbox_header a { - color: #6fc992; -} -.swagger-ui-wrap ul#resources li.resource ul.endpoints li.endpoint ul.operations li.operation.patch div.heading { - background-color: #FCE9E3; - border: 1px solid #F5D5C3; -} -.swagger-ui-wrap ul#resources li.resource ul.endpoints li.endpoint ul.operations li.operation.patch div.heading h3 span.http_method a { - background-color: #D38042; -} -.swagger-ui-wrap ul#resources li.resource ul.endpoints li.endpoint ul.operations li.operation.patch div.heading ul.options li { - border-right: 1px solid #dddddd; - border-right-color: #f0cecb; - color: #D38042; -} -.swagger-ui-wrap ul#resources li.resource ul.endpoints li.endpoint ul.operations li.operation.patch div.heading ul.options li a { - color: #D38042; -} -.swagger-ui-wrap ul#resources li.resource ul.endpoints li.endpoint ul.operations li.operation.patch div.content { - background-color: #faf0ef; - border: 1px solid #f0cecb; -} -.swagger-ui-wrap ul#resources li.resource ul.endpoints li.endpoint ul.operations li.operation.patch div.content h4 { - color: #D38042; -} -.swagger-ui-wrap ul#resources li.resource ul.endpoints li.endpoint ul.operations li.operation.patch div.content div.sandbox_header a { - color: #dcb67f; -} -.swagger-ui-wrap ul#resources li.resource ul.endpoints li.endpoint ul.operations li.operation.get div.heading { - background-color: #e7f0f7; - border: 1px solid #c3d9ec; -} -.swagger-ui-wrap ul#resources li.resource ul.endpoints li.endpoint ul.operations li.operation.get div.heading h3 span.http_method a { - background-color: #0f6ab4; -} -.swagger-ui-wrap ul#resources li.resource ul.endpoints li.endpoint ul.operations li.operation.get div.heading ul.options li { - border-right: 1px solid #dddddd; - border-right-color: #c3d9ec; - color: #0f6ab4; -} -.swagger-ui-wrap ul#resources li.resource ul.endpoints li.endpoint ul.operations li.operation.get div.heading ul.options li a { - color: #0f6ab4; -} -.swagger-ui-wrap ul#resources li.resource ul.endpoints li.endpoint ul.operations li.operation.get div.content { - background-color: #ebf3f9; - border: 1px solid #c3d9ec; -} -.swagger-ui-wrap ul#resources li.resource ul.endpoints li.endpoint ul.operations li.operation.get div.content h4 { - color: #0f6ab4; -} -.swagger-ui-wrap ul#resources li.resource ul.endpoints li.endpoint ul.operations li.operation.get div.content div.sandbox_header a { - color: #6fa5d2; -} -.swagger-ui-wrap ul#resources li.resource ul.endpoints li.endpoint ul.operations li.operation.get div.content, -.swagger-ui-wrap ul#resources li.resource ul.endpoints li.endpoint ul.operations li.operation.post div.content, -.swagger-ui-wrap ul#resources li.resource ul.endpoints li.endpoint ul.operations li.operation.head div.content, -.swagger-ui-wrap ul#resources li.resource ul.endpoints li.endpoint ul.operations li.operation.put div.content, -.swagger-ui-wrap ul#resources li.resource ul.endpoints li.endpoint ul.operations li.operation.patch div.content, -.swagger-ui-wrap ul#resources li.resource ul.endpoints li.endpoint ul.operations li.operation.delete div.content { - border-top: none; -} -.swagger-ui-wrap ul#resources li.resource ul.endpoints li.endpoint ul.operations li.operation.get div.heading ul.options li:last-child, -.swagger-ui-wrap ul#resources li.resource ul.endpoints li.endpoint ul.operations li.operation.post div.heading ul.options li:last-child, -.swagger-ui-wrap ul#resources li.resource ul.endpoints li.endpoint ul.operations li.operation.head div.heading ul.options li:last-child, -.swagger-ui-wrap ul#resources li.resource ul.endpoints li.endpoint ul.operations li.operation.put div.heading ul.options li:last-child, -.swagger-ui-wrap ul#resources li.resource ul.endpoints li.endpoint ul.operations li.operation.patch div.heading ul.options li:last-child, -.swagger-ui-wrap ul#resources li.resource ul.endpoints li.endpoint ul.operations li.operation.delete div.heading ul.options li:last-child, -.swagger-ui-wrap ul#resources li.resource ul.endpoints li.endpoint ul.operations li.operation.get div.heading ul.options li.last, -.swagger-ui-wrap ul#resources li.resource ul.endpoints li.endpoint ul.operations li.operation.post div.heading ul.options li.last, -.swagger-ui-wrap ul#resources li.resource ul.endpoints li.endpoint ul.operations li.operation.head div.heading ul.options li.last, -.swagger-ui-wrap ul#resources li.resource ul.endpoints li.endpoint ul.operations li.operation.put div.heading ul.options li.last, -.swagger-ui-wrap ul#resources li.resource ul.endpoints li.endpoint ul.operations li.operation.patch div.heading ul.options li.last, -.swagger-ui-wrap ul#resources li.resource ul.endpoints li.endpoint ul.operations li.operation.delete div.heading ul.options li.last { - padding-right: 0; - border-right: none; -} -.swagger-ui-wrap ul#resources li.resource ul.endpoints li.endpoint ul.operations ul.options li a:hover, -.swagger-ui-wrap ul#resources li.resource ul.endpoints li.endpoint ul.operations ul.options li a:active, -.swagger-ui-wrap ul#resources li.resource ul.endpoints li.endpoint ul.operations ul.options li a.active { - text-decoration: underline; -} -.swagger-ui-wrap ul#resources li.resource ul.endpoints li.endpoint ul.operations ul.options li:first-child, -.swagger-ui-wrap ul#resources li.resource ul.endpoints li.endpoint ul.operations ul.options li.first { - padding-left: 0; -} -.swagger-ui-wrap ul#resources li.resource ul.endpoints li.endpoint ul.operations:first-child, -.swagger-ui-wrap ul#resources li.resource ul.endpoints li.endpoint ul.operations.first { - padding-left: 0; -} -.swagger-ui-wrap p#colophon { - margin: 0 15px 40px 15px; - padding: 10px 0; - font-size: 0.8em; - border-top: 1px solid #dddddd; - font-family: "Droid Sans", sans-serif; - color: #999999; - font-style: italic; -} -.swagger-ui-wrap p#colophon a { - text-decoration: none; - color: #547f00; -} -.swagger-ui-wrap h3 { - color: black; - font-size: 1.1em; - padding: 10px 0 10px 0; -} -.swagger-ui-wrap .markdown ol, -.swagger-ui-wrap .markdown ul { - font-family: "Droid Sans", sans-serif; - margin: 5px 0 10px; - padding: 0 0 0 18px; - list-style-type: disc; -} -.swagger-ui-wrap form.form_box { - background-color: #ebf3f9; - border: 1px solid #c3d9ec; - padding: 10px; -} -.swagger-ui-wrap form.form_box label { - color: #0f6ab4 !important; -} -.swagger-ui-wrap form.form_box input[type=submit] { - display: block; - padding: 10px; -} -.swagger-ui-wrap form.form_box p.weak { - font-size: 0.8em; -} -.swagger-ui-wrap form.form_box p { - font-size: 0.9em; - padding: 0 0 15px; - color: #7e7b6d; -} -.swagger-ui-wrap form.form_box p a { - color: #646257; -} -.swagger-ui-wrap form.form_box p strong { - color: black; -} -#header { - background-color: #89bf04; - padding: 14px; -} -#header a#logo { - font-size: 1.5em; - font-weight: bold; - text-decoration: none; - background: transparent url(../images/logo_small.png) no-repeat left center; - padding: 20px 0 20px 40px; - color: white; -} -#header form#api_selector { - display: block; - clear: none; - float: right; -} -#header form#api_selector .input { - display: block; - clear: none; - float: left; - margin: 0 10px 0 0; -} -#header form#api_selector .input input#input_apiKey { - width: 200px; -} -#header form#api_selector .input input#input_baseUrl { - width: 400px; -} -#header form#api_selector .input a#explore { - display: block; - text-decoration: none; - font-weight: bold; - padding: 6px 8px; - font-size: 0.9em; - color: white; - background-color: #547f00; - -moz-border-radius: 4px; - -webkit-border-radius: 4px; - -o-border-radius: 4px; - -ms-border-radius: 4px; - -khtml-border-radius: 4px; - border-radius: 4px; -} -#header form#api_selector .input a#explore:hover { - background-color: #547f00; -} -#header form#api_selector .input input { - font-size: 0.9em; - padding: 3px; - margin: 0; -} -#content_message { - margin: 10px 15px; - font-style: italic; - color: #999999; -} -#message-bar { - min-height: 30px; - text-align: center; - padding-top: 10px; -} diff --git a/fixtures/v1.2/helloworld/server/src/main/webapp/images/logo_small.png b/fixtures/v1.2/helloworld/server/src/main/webapp/images/logo_small.png deleted file mode 100644 index 5496a65579..0000000000 Binary files a/fixtures/v1.2/helloworld/server/src/main/webapp/images/logo_small.png and /dev/null differ diff --git a/fixtures/v1.2/helloworld/server/src/main/webapp/images/pet_store_api.png b/fixtures/v1.2/helloworld/server/src/main/webapp/images/pet_store_api.png deleted file mode 100644 index f9f9cd4aeb..0000000000 Binary files a/fixtures/v1.2/helloworld/server/src/main/webapp/images/pet_store_api.png and /dev/null differ diff --git a/fixtures/v1.2/helloworld/server/src/main/webapp/images/throbber.gif b/fixtures/v1.2/helloworld/server/src/main/webapp/images/throbber.gif deleted file mode 100644 index 0639388924..0000000000 Binary files a/fixtures/v1.2/helloworld/server/src/main/webapp/images/throbber.gif and /dev/null differ diff --git a/fixtures/v1.2/helloworld/server/src/main/webapp/images/wordnik_api.png b/fixtures/v1.2/helloworld/server/src/main/webapp/images/wordnik_api.png deleted file mode 100644 index dca4f1455a..0000000000 Binary files a/fixtures/v1.2/helloworld/server/src/main/webapp/images/wordnik_api.png and /dev/null differ diff --git a/fixtures/v1.2/helloworld/server/src/main/webapp/index.html b/fixtures/v1.2/helloworld/server/src/main/webapp/index.html deleted file mode 100644 index 44cc371783..0000000000 --- a/fixtures/v1.2/helloworld/server/src/main/webapp/index.html +++ /dev/null @@ -1,78 +0,0 @@ - - - - Swagger UI - - - - - - - - - - - - - - - - - - - - -
-   -
- -
- -
- - - - diff --git a/fixtures/v1.2/helloworld/server/src/main/webapp/lib/backbone-min.js b/fixtures/v1.2/helloworld/server/src/main/webapp/lib/backbone-min.js deleted file mode 100644 index c1c0d4fff2..0000000000 --- a/fixtures/v1.2/helloworld/server/src/main/webapp/lib/backbone-min.js +++ /dev/null @@ -1,38 +0,0 @@ -// Backbone.js 0.9.2 - -// (c) 2010-2012 Jeremy Ashkenas, DocumentCloud Inc. -// Backbone may be freely distributed under the MIT license. -// For all details and documentation: -// http://backbonejs.org -(function(){var l=this,y=l.Backbone,z=Array.prototype.slice,A=Array.prototype.splice,g;g="undefined"!==typeof exports?exports:l.Backbone={};g.VERSION="0.9.2";var f=l._;!f&&"undefined"!==typeof require&&(f=require("underscore"));var i=l.jQuery||l.Zepto||l.ender;g.setDomLibrary=function(a){i=a};g.noConflict=function(){l.Backbone=y;return this};g.emulateHTTP=!1;g.emulateJSON=!1;var p=/\s+/,k=g.Events={on:function(a,b,c){var d,e,f,g,j;if(!b)return this;a=a.split(p);for(d=this._callbacks||(this._callbacks= -{});e=a.shift();)f=(j=d[e])?j.tail:{},f.next=g={},f.context=c,f.callback=b,d[e]={tail:g,next:j?j.next:f};return this},off:function(a,b,c){var d,e,h,g,j,q;if(e=this._callbacks){if(!a&&!b&&!c)return delete this._callbacks,this;for(a=a?a.split(p):f.keys(e);d=a.shift();)if(h=e[d],delete e[d],h&&(b||c))for(g=h.tail;(h=h.next)!==g;)if(j=h.callback,q=h.context,b&&j!==b||c&&q!==c)this.on(d,j,q);return this}},trigger:function(a){var b,c,d,e,f,g;if(!(d=this._callbacks))return this;f=d.all;a=a.split(p);for(g= -z.call(arguments,1);b=a.shift();){if(c=d[b])for(e=c.tail;(c=c.next)!==e;)c.callback.apply(c.context||this,g);if(c=f){e=c.tail;for(b=[b].concat(g);(c=c.next)!==e;)c.callback.apply(c.context||this,b)}}return this}};k.bind=k.on;k.unbind=k.off;var o=g.Model=function(a,b){var c;a||(a={});b&&b.parse&&(a=this.parse(a));if(c=n(this,"defaults"))a=f.extend({},c,a);b&&b.collection&&(this.collection=b.collection);this.attributes={};this._escapedAttributes={};this.cid=f.uniqueId("c");this.changed={};this._silent= -{};this._pending={};this.set(a,{silent:!0});this.changed={};this._silent={};this._pending={};this._previousAttributes=f.clone(this.attributes);this.initialize.apply(this,arguments)};f.extend(o.prototype,k,{changed:null,_silent:null,_pending:null,idAttribute:"id",initialize:function(){},toJSON:function(){return f.clone(this.attributes)},get:function(a){return this.attributes[a]},escape:function(a){var b;if(b=this._escapedAttributes[a])return b;b=this.get(a);return this._escapedAttributes[a]=f.escape(null== -b?"":""+b)},has:function(a){return null!=this.get(a)},set:function(a,b,c){var d,e;f.isObject(a)||null==a?(d=a,c=b):(d={},d[a]=b);c||(c={});if(!d)return this;d instanceof o&&(d=d.attributes);if(c.unset)for(e in d)d[e]=void 0;if(!this._validate(d,c))return!1;this.idAttribute in d&&(this.id=d[this.idAttribute]);var b=c.changes={},h=this.attributes,g=this._escapedAttributes,j=this._previousAttributes||{};for(e in d){a=d[e];if(!f.isEqual(h[e],a)||c.unset&&f.has(h,e))delete g[e],(c.silent?this._silent: -b)[e]=!0;c.unset?delete h[e]:h[e]=a;!f.isEqual(j[e],a)||f.has(h,e)!=f.has(j,e)?(this.changed[e]=a,c.silent||(this._pending[e]=!0)):(delete this.changed[e],delete this._pending[e])}c.silent||this.change(c);return this},unset:function(a,b){(b||(b={})).unset=!0;return this.set(a,null,b)},clear:function(a){(a||(a={})).unset=!0;return this.set(f.clone(this.attributes),a)},fetch:function(a){var a=a?f.clone(a):{},b=this,c=a.success;a.success=function(d,e,f){if(!b.set(b.parse(d,f),a))return!1;c&&c(b,d)}; -a.error=g.wrapError(a.error,b,a);return(this.sync||g.sync).call(this,"read",this,a)},save:function(a,b,c){var d,e;f.isObject(a)||null==a?(d=a,c=b):(d={},d[a]=b);c=c?f.clone(c):{};if(c.wait){if(!this._validate(d,c))return!1;e=f.clone(this.attributes)}a=f.extend({},c,{silent:!0});if(d&&!this.set(d,c.wait?a:c))return!1;var h=this,i=c.success;c.success=function(a,b,e){b=h.parse(a,e);if(c.wait){delete c.wait;b=f.extend(d||{},b)}if(!h.set(b,c))return false;i?i(h,a):h.trigger("sync",h,a,c)};c.error=g.wrapError(c.error, -h,c);b=this.isNew()?"create":"update";b=(this.sync||g.sync).call(this,b,this,c);c.wait&&this.set(e,a);return b},destroy:function(a){var a=a?f.clone(a):{},b=this,c=a.success,d=function(){b.trigger("destroy",b,b.collection,a)};if(this.isNew())return d(),!1;a.success=function(e){a.wait&&d();c?c(b,e):b.trigger("sync",b,e,a)};a.error=g.wrapError(a.error,b,a);var e=(this.sync||g.sync).call(this,"delete",this,a);a.wait||d();return e},url:function(){var a=n(this,"urlRoot")||n(this.collection,"url")||t(); -return this.isNew()?a:a+("/"==a.charAt(a.length-1)?"":"/")+encodeURIComponent(this.id)},parse:function(a){return a},clone:function(){return new this.constructor(this.attributes)},isNew:function(){return null==this.id},change:function(a){a||(a={});var b=this._changing;this._changing=!0;for(var c in this._silent)this._pending[c]=!0;var d=f.extend({},a.changes,this._silent);this._silent={};for(c in d)this.trigger("change:"+c,this,this.get(c),a);if(b)return this;for(;!f.isEmpty(this._pending);){this._pending= -{};this.trigger("change",this,a);for(c in this.changed)!this._pending[c]&&!this._silent[c]&&delete this.changed[c];this._previousAttributes=f.clone(this.attributes)}this._changing=!1;return this},hasChanged:function(a){return!arguments.length?!f.isEmpty(this.changed):f.has(this.changed,a)},changedAttributes:function(a){if(!a)return this.hasChanged()?f.clone(this.changed):!1;var b,c=!1,d=this._previousAttributes,e;for(e in a)if(!f.isEqual(d[e],b=a[e]))(c||(c={}))[e]=b;return c},previous:function(a){return!arguments.length|| -!this._previousAttributes?null:this._previousAttributes[a]},previousAttributes:function(){return f.clone(this._previousAttributes)},isValid:function(){return!this.validate(this.attributes)},_validate:function(a,b){if(b.silent||!this.validate)return!0;var a=f.extend({},this.attributes,a),c=this.validate(a,b);if(!c)return!0;b&&b.error?b.error(this,c,b):this.trigger("error",this,c,b);return!1}});var r=g.Collection=function(a,b){b||(b={});b.model&&(this.model=b.model);b.comparator&&(this.comparator=b.comparator); -this._reset();this.initialize.apply(this,arguments);a&&this.reset(a,{silent:!0,parse:b.parse})};f.extend(r.prototype,k,{model:o,initialize:function(){},toJSON:function(a){return this.map(function(b){return b.toJSON(a)})},add:function(a,b){var c,d,e,g,i,j={},k={},l=[];b||(b={});a=f.isArray(a)?a.slice():[a];c=0;for(d=a.length;c=b))this.iframe=i('