Skip to content

Commit 60a1bb5

Browse files
miquimiqui
authored
Merge pull request #157 from baywet/chore/sync-main-tov1.1-dev
sync main to v1.1-dev
2 parents 13b0a70 + 7f65deb commit 60a1bb5

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

63 files changed

+1555
-31
lines changed

‎.github/CODEOWNERS‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
* @oai/tsc

‎.github/templates/agenda.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,7 @@
33

44

55

6-
Meeting link:
6+
Meeting link: <https://zoom-lfx.platform.linuxfoundation.org/meeting/99628896838?password=f3ff9796-d6a0-4749-b39e-93dc7eafe7cd>
77

88

99

‎.github/workflows/agenda.yaml‎

Lines changed: 9 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,9 @@ name: Create meeting template
22

33
on:
44
workflow_dispatch: {}
5+
schedule:
6+
# every two weeks on tuesday at 10AM PST (with DST)
7+
- cron: '0 17 */14 * 2'
58

69
jobs:
710
create-discussion:
@@ -16,6 +19,11 @@ jobs:
1619
echo 'AGENDA<<EOF' >> $GITHUB_ENV
1720
cat .github/templates/agenda.md >> $GITHUB_ENV
1821
echo 'EOF' >> $GITHUB_ENV
22+
- name: Get Next Meeting Date
23+
id: get-next-meeting-date
24+
run: |
25+
NEXT_MEETING_DATE=$(date -d "next Tuesday" +%Y-%m-%d)
26+
echo "NEXT_MEETING_DATE=$NEXT_MEETING_DATE" >> $GITHUB_ENV
1927
- name: Create discussion with agenda
2028
id: create-repository-discussion
2129
uses: octokit/[email protected]
@@ -24,7 +32,7 @@ jobs:
2432
with:
2533
variables: |
2634
body: "${{ env.AGENDA }}"
27-
title: "Overlays Meeting"
35+
title: "Overlays Meeting (${{ env.NEXT_MEETING_DATE }})"
2836
repositoryId: 'MDEwOlJlcG9zaXRvcnkzNTk4NjU5MDI='
2937
categoryId: 'DIC_kwDOFXMeLs4COVB8'
3038
query: |

‎.github/workflows/respec.yaml‎

Lines changed: 14 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -19,9 +19,18 @@ jobs:
1919
respec:
2020
if: github.repository == 'OAI/Overlay-Specification'
2121

22-
runs-on: ubuntu-latest
22+
runs-on: ubuntu-22.04
2323

2424
steps:
25+
- name: Generate access token
26+
id: generate-token
27+
uses: actions/create-github-app-token@v1
28+
with:
29+
app-id: ${{ secrets.OAI_SPEC_PUBLISHER_APPID }}
30+
private-key: ${{ secrets.OAI_SPEC_PUBLISHER_PRIVATE_KEY }}
31+
owner: OAI
32+
repositories: OpenAPI-Specification
33+
2534
- uses: actions/checkout@v4 # checkout main branch
2635
with:
2736
fetch-depth: 0
@@ -35,7 +44,7 @@ jobs:
3544

3645
- uses: actions/checkout@v4 # checkout gh-pages branch
3746
with:
38-
token: ${{ secrets.OAS_REPO_TOKEN }}
47+
token: ${{ steps.generate-token.outputs.token }}
3948
repository: OAI/OpenAPI-Specification # TODO: change to OAI/...
4049
ref: gh-pages
4150
path: deploy
@@ -46,16 +55,14 @@ jobs:
4655
- name: Create Pull Request
4756
uses: peter-evans/create-pull-request@v7
4857
with:
49-
# A personal access token is required to push changes to the repository.
50-
# This token needs to be refreshed regularly and stored in the repository secrets.
51-
token: ${{ secrets.OAS_REPO_TOKEN }}
58+
token: ${{ steps.generate-token.outputs.token }}
5259
branch: update-overlay-respec-version
5360
base: gh-pages
5461
delete-branch: true
5562
path: deploy
5663
labels: Housekeeping
57-
team-reviewers: OAI/tsc
58-
title: Update ReSpec-rendered specification versions for Overlay
64+
reviewers: darrelmiller,webron,earth2marsh,lornajane,mikekistler,miqui,handrews,ralfhandl
65+
title: Overlay - Update ReSpec-rendered specification versions
5966
commit-message: Update ReSpec-rendered specification versions
6067
signoff: true
6168
body: |

‎.github/workflows/schema-publish.yaml‎

Lines changed: 66 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,66 @@
1+
name: schema-publish
2+
3+
# author: @ralfhandl
4+
5+
#
6+
# This workflow copies the x.y schemas to the gh-pages branch
7+
#
8+
9+
# run this on push to main
10+
on:
11+
push:
12+
branches:
13+
- main
14+
workflow_dispatch: {}
15+
16+
jobs:
17+
publish:
18+
runs-on: ubuntu-latest
19+
20+
steps:
21+
- name: Generate access token
22+
id: generate-token
23+
uses: actions/create-github-app-token@v1
24+
with:
25+
app-id: ${{ secrets.OAI_SPEC_PUBLISHER_APPID }}
26+
private-key: ${{ secrets.OAI_SPEC_PUBLISHER_PRIVATE_KEY }}
27+
owner: OAI
28+
repositories: OpenAPI-Specification
29+
30+
- uses: actions/checkout@v4 # checkout main branch
31+
with:
32+
fetch-depth: 0
33+
34+
- uses: actions/setup-node@v4 # setup Node.js
35+
with:
36+
node-version: 20.x
37+
38+
- name: Install dependencies
39+
run: npm ci
40+
41+
- uses: actions/checkout@v4 # checkout gh-pages branch
42+
with:
43+
token: ${{ steps.generate-token.outputs.token }}
44+
repository: OAI/OpenAPI-Specification
45+
ref: gh-pages
46+
path: deploy
47+
48+
- name: run main script
49+
run: scripts/schema-publish.sh
50+
51+
- name: Create Pull Request
52+
uses: peter-evans/create-pull-request@v7
53+
with:
54+
token: ${{ steps.generate-token.outputs.token }}
55+
branch: publish-overlay-schema-iteration
56+
base: gh-pages
57+
delete-branch: true
58+
path: deploy
59+
labels: Housekeeping,Schema
60+
reviewers: darrelmiller,webron,earth2marsh,lornajane,mikekistler,miqui,handrews,ralfhandl
61+
title: Overlay - Publish Schema Iterations
62+
commit-message: New Overlay schema iterations
63+
signoff: true
64+
body: |
65+
This pull request is automatically triggered by GitHub action `schema-publish` in the OAI/Overlay-Specification repo.
66+
The `schemas/**/*.yaml` files have changed and JSON files are automatically generated.

‎CONTRIBUTING.md‎

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,38 @@ Pull requests are also welcome, but it is recommended to create an issue first,
77
Questions and comments are also welcome - use the GitHub Discussions feature.
88
You will also find notes from past meetings in the Discussion tab.
99

10+
## Key information
11+
12+
This project is covered by our [Code of Conduct](https://github.com/OAI/OpenAPI-Specification?tab=coc-ov-file#readme).
13+
All participants are expected to read and follow this code.
14+
15+
No changes, however trivial, are ever made to the contents of published specifications (the files in the `versions/` folder).
16+
Exceptions may be made when links to external documents have been changed by a 3rd party, in order to keep our documents accurate.
17+
18+
Published versions of the specification are in the `versions/` folder.
19+
The under-development versions of the specification are in the file `src/overlay.md` on the appropriately-versioned branch.
20+
For example, work on the next release for 1.1 is on `v1.1-dev` in the file `src/overlay.md`.
21+
22+
The [spec site](https://spec.openapis.org) is the source of truth for the OpenAPI Overlay specification as it contains all the citations and author credits.
23+
24+
The OpenAPI project is almost entirely staffed by volunteers.
25+
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.
26+
27+
## Pull Requests
28+
29+
Pull requests are always welcome but please read the section below on [branching strategy](#branching-strategy) before you start.
30+
31+
Pull requests must come from a fork; create a fresh branch on your fork based on the target branch for your change.
32+
33+
### Branching Strategy
34+
35+
Overview of branches:
36+
37+
- `main` holds the published versions of the specification, utility scripts and supporting documentation.
38+
- `dev` is for development infrastructure and other changes that apply to multiple versions of development.
39+
- Branches named `vX.Y-dev` are the active development branches for future releases.
40+
All changes should be applied to the _earliest_ branch where the changes are relevant in the first instance.
41+
1042
## Build the HTML version to publish
1143

1244
We use ReSpec to render the markdown specification as HTML for publishing and easier reading.

‎README.md‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -21,6 +21,11 @@ If you are looking for tools to use with Overlays, try these:
2121
- [Speakeasy CLI](https://www.speakeasy.com/docs/speakeasy-cli/getting-started)
2222
- [overlays-js](https://github.com/lornajane/openapi-overlays-js)
2323
- [apigee-go-gen CLI](https://apigee.github.io/apigee-go-gen/transform/commands/oas-overlay/)
24+
- [openapi-format CLI/UI](https://github.com/thim81/openapi-format)
25+
- [oas-patch CLI](https://github.com/mcroissant/oas_patcher)
26+
- [oas-overlay-java](https://github.com/IBM/oas-overlay-java)
27+
- [Specmatic](https://specmatic.io/) - [Docs](https://docs.specmatic.io/documentation/contract_tests.html#overlays)
28+
- [BinkyLabs.OpenApi.Overlays - dotnet](https://github.com/BinkyLabs/openapi-overlays-dotnet)
2429

2530
(Is something missing from the list? Send us a pull request to add it!)
2631

‎compliant-sets/README.md‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
# OpenAPI Overlay Compliant Sets
2+
3+
The folders in this directory contain sets of "known good" Overlays, along with OpenAPI descriptions before and after the Overlay.
4+
These files are offered as examples of how a series of Overlays are expected to be applied, with the aim of supporting people building tools that apply Overlays.
5+
6+
Each directory contains:
7+
- `overlay.yaml` - the Overlay
8+
- `openapi.yaml` - an OpenAPI description to use
9+
- `output.yaml` - the OpenAPI description after the Overlay has been applied

‎compliant-sets/add-a-license/openapi.yaml‎

Lines changed: 70 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,70 @@
1+
openapi: 3.1.0
2+
info:
3+
version: 1.0.0
4+
title: Imaginary town
5+
servers:
6+
- url: 'https://example.com'
7+
description: Example server
8+
paths:
9+
/buildings:
10+
get:
11+
summary: All buildings
12+
operationId: buildingsList
13+
responses:
14+
'200':
15+
description: Return all known buildings
16+
content:
17+
application/json:
18+
schema:
19+
type: array
20+
items:
21+
$ref: '#/components/schemas/Building'
22+
'/buildings/{buildingId}':
23+
get:
24+
summary: Specific building
25+
operationId: buildingById
26+
parameters:
27+
- name: buildingId
28+
in: path
29+
required: true
30+
description: Which building to return
31+
schema:
32+
type: string
33+
responses:
34+
'200':
35+
description: Return a building
36+
content:
37+
application/json:
38+
schema:
39+
$ref: '#/components/schemas/Building'
40+
/locations:
41+
get:
42+
summary: All locations
43+
operationId: locationList
44+
responses:
45+
'200':
46+
description: Returns all locations
47+
content:
48+
application/json:
49+
schema:
50+
type: array
51+
items:
52+
type: object
53+
properties:
54+
location_id:
55+
type: integer
56+
example: 44
57+
name:
58+
type: string
59+
example: North Village
60+
components:
61+
schemas:
62+
Building:
63+
type: object
64+
properties:
65+
building:
66+
type: string
67+
example: house
68+
location_id:
69+
type: integer
70+
example: 44

‎compliant-sets/add-a-license/output.yaml‎

Lines changed: 74 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,74 @@
1+
openapi: 3.1.0
2+
info:
3+
version: 1.0.0
4+
title: Imaginary town
5+
license:
6+
name: MIT
7+
url: 'https://opensource.org/licenses/MIT'
8+
servers:
9+
- url: 'https://example.com'
10+
description: Example server
11+
paths:
12+
/buildings:
13+
get:
14+
summary: All buildings
15+
operationId: buildingsList
16+
responses:
17+
'200':
18+
description: Return all known buildings
19+
content:
20+
application/json:
21+
schema:
22+
type: array
23+
items:
24+
$ref: '#/components/schemas/Building'
25+
'/buildings/{buildingId}':
26+
get:
27+
summary: Specific building
28+
operationId: buildingById
29+
parameters:
30+
- name: buildingId
31+
in: path
32+
required: true
33+
description: Which building to return
34+
schema:
35+
type: string
36+
responses:
37+
'200':
38+
description: Return a building
39+
content:
40+
application/json:
41+
schema:
42+
$ref: '#/components/schemas/Building'
43+
/locations:
44+
get:
45+
summary: All locations
46+
operationId: locationList
47+
responses:
48+
'200':
49+
description: Returns all locations
50+
content:
51+
application/json:
52+
schema:
53+
type: array
54+
items:
55+
type: object
56+
properties:
57+
location_id:
58+
type: integer
59+
example: 44
60+
name:
61+
type: string
62+
example: North Village
63+
components:
64+
schemas:
65+
Building:
66+
type: object
67+
properties:
68+
building:
69+
type: string
70+
example: house
71+
location_id:
72+
type: integer
73+
example: 44
74+

0 commit comments

Comments
 (0)