diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index d450c89763..3b6614769b 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -2,7 +2,8 @@ ## Building the site -The registy site uses [jekyll](https://jekyllrb.com/), a Ruby based static site generator, with the Dinky theme. +The registry site uses [jekyll](https://jekyllrb.com/), +a Ruby based static site generator, with the Dinky theme. ### Docker dev @@ -28,9 +29,10 @@ With all the gems (dependencies) installed, you can launch the jekyll server. bundle exec jekyll serve ``` -It will show output like this, and you can grab the Server address and open it in your browser. +It will show output like this, and you can grab the Server address +and open it in your browser. -``` +```md Configuration file: /site/_config.yml Source: /site Destination: /site/_site @@ -41,3 +43,123 @@ Configuration file: /site/_config.yml Server address: http://0.0.0.0:4000 ``` +## Adding New Entries to the Registries + +To add a new entry to the registries (either an OpenAPI +Specification Extension namespace or a specific OpenAPI +Specification Extension), +fork this repository in GitHub. +Make a local clone of your fork and check out the +`gh-pages` branch. + +### Add a New Extension Namespace Registry Entry + +Working in the `gh-pages` branch, +add a new Markdown file in `registries/_namespace/`. The file name +should be the namespace name with a `.md` extension. For example, +to add an extension namespace `abc` for extensions named `x-abc-*`, +create `registries/_namespace/abc.md`. Use the following template, +replacing the instruction text in `<>` markers: + +```md +--- +owner: <> +issue: +description: <> +layout: default +--- + +{% capture summary %} +The `x-{{page.slug}}-` prefix is reserved for extensions created by +<> +{% endcapture %} + +{% include namespace-entry.md summary=summary %} + +``` + +You may use [GitHub Flavored Markdown](https://github.github.com/gfm/) +in the short and long descriptions. + +See [oai.md](https://raw.githubusercontent.com/OAI/OpenAPI-Specification/refs/heads/gh-pages/registries/_namespace/oai.md) +for an example for the `x-oai-*` namespace. + +Next, locally build +the site as described above and view +[http://127.0.0.1:4000/registry/namespace/index.html](http://127.0.0.1:4000/registry/namespace/index.html) +to verify your namespace is listed. +(Modify the URL if Jekyll is running on a different IP or port.) +The namespace name in Value column +should link to your namespace page, and the __Description__ +text should be the `description:` from the Markdown frontmatter. + +Preview your content at +`http://127.0.0.1:4000/registry/namespace/abc.html` +(change `abc` in to your namespace URL). + +### Add a New Specification Extension Registry Entry + +add a new Markdown file in `registries/_extension/`. +The file name should be your specification extension name with +a `.md` file extension, such as +`registries/_extension/x-abc-wander.md` to document the +`x-abc-wander` extension. + +Use this template for your file, +replacing the instruction text in `<>` markers: + +```md +--- +owner: <> +issue: +description: <>. +schema: + <> + objects: <> +layout: default +--- + +{% capture summary %} +<> + +Used by: (informational) + + * <>> +{% endcapture %} + +{% capture example %} + +< + +{% endcapture %} + +{% include extension-entry.md summary=summary example=example %} +``` + +You may use [GitHub Flavored Markdown](https://github.github.com/gfm/) +in the short and long descriptions. + +See [x-twitter.md](https://raw.githubusercontent.com/OAI/OpenAPI-Specification/refs/heads/gh-pages/registries/_extension/x-twitter.md) +for an example. + +Build the site locally as described above. + +Preview [http://127.0.0.1:4000/registry/extension/](http://127.0.0.1:4000/registry/extension/). + +(Modify the URL if Jekyll is running on a different IP or port.) +Verify that you specification extension +should is listed. The __Value__ column should contain you extension name +with a link to you documentation, such as +`http://127.0.0.1:4000/registry/extension/x-abc-wander.html`, +and the __Description__ should be your brief description. + +### Submitting + +When you have verified your content renders correctly, +submit a Pull Request against the `gh-pages` branch +of `git@github.com:OAI/OpenAPI-Specification.git`. +Committers will review the PR and you may be asked +to update the PR. When approved, committers +will merge your PR into `git@github.com:OAI/OpenAPI-Specification.git` +and the merge actions will publish your changes to +[https://spec.openapis.org/registry/](https://spec.openapis.org/registry/). diff --git a/registries/_namespace/fdx.md b/registries/_namespace/fdx.md new file mode 100644 index 0000000000..a932f205c9 --- /dev/null +++ b/registries/_namespace/fdx.md @@ -0,0 +1,18 @@ +--- +owner: DavidBiesack +issue: +description: Extensions created and used by [Financial Data Exchange (FDX)](https://financialdataexchange.org) +layout: default +--- + +{% capture summary %} +The `x-{{page.slug}}-` prefix is reserved for extensions created by +[Financial Data Exchange (FDX)](https://financialdataexchange.org). +FDX is the +[standard-setting organization](https://www.consumerfinance.gov/about-us/newsroom/cfpb-approves-application-from-financial-data-exchange-to-issue-standards-for-open-banking/) which is defining the open banking +standard in the US under +[Dodd-Frank Section 1033](https://www.consumerfinance.gov/rules-policy/notice-opportunities-comment/archive-closed/dodd-frank-act-section-1033-consumer-access-to-financial-records/). + +{% endcapture %} + +{% include namespace-entry.md summary=summary %} diff --git a/registry/extension.md b/registry/extension.md index 226b8730e7..8bf28d4020 100644 --- a/registry/extension.md +++ b/registry/extension.md @@ -13,7 +13,11 @@ parent: Registry ## Contributing -Please raise a [Pull-Request](https://github.com/OAI/OpenAPI-Specification/pulls) or [Issue](https://github.com/OAI/OpenAPI-Specification/issues) to contribute or discuss a registry value. +Please raise a [Pull-Request](https://github.com/OAI/OpenAPI-Specification/pulls) and +follow the instructions in the +[`CONTRIBUTING.md` file in the `gh-pages` branch](https://github.com/OAI/OpenAPI-Specification/blob/gh-pages/CONTRIBUTING.md), +or open an [Issue](https://github.com/OAI/OpenAPI-Specification/issues) +to contribute or discuss a registry value. ## Values @@ -21,4 +25,3 @@ Please raise a [Pull-Request](https://github.com/OAI/OpenAPI-Specification/pulls |---|---|---| {% for value in site.extension %}| {{ value.slug }} | {{ value.description }} | {% if value.issue %}#{{ value.issue }}{% endif %} | {% endfor %} - diff --git a/registry/namespace.md b/registry/namespace.md index 6b05c8c1b7..9f2ee6d483 100644 --- a/registry/namespace.md +++ b/registry/namespace.md @@ -11,7 +11,12 @@ To allow for creators of OpenAPI descriptions to define new extensions without t ## Contributing -Please raise a [Pull-Request](https://github.com/OAI/OpenAPI-Specification/pulls) or [Issue](https://github.com/OAI/OpenAPI-Specification/issues) to contribute or discuss a registry value. +Please raise a +[Pull-Request](https://github.com/OAI/OpenAPI-Specification/pulls) and +follow the instructions in the +[`CONTRIBUTING.md` file in the `gh-pages` branch](https://github.com/OAI/OpenAPI-Specification/blob/gh-pages/CONTRIBUTING.md), +or open an [Issue](https://github.com/OAI/OpenAPI-Specification/issues) +to contribute or discuss a registry value. ## Values