Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Voeg contact informatie toe aan OpenAPI document #161

Open
wants to merge 3 commits into
base: develop
Choose a base branch
from
Open

Voeg contact informatie toe aan OpenAPI document #161

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
3483e01
Voeg contact informatie toe aan OpenAPI document
TimvdLippe Jan 22, 2025
5b1f571
Specificeer dat generieke contact informatie niet de bedoeling is
TimvdLippe Jan 23, 2025
ce702db
Voeg voorbeeld toe voor contact informatie
TimvdLippe Feb 5, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
29 changes: 29 additions & 0 deletions DesignRules.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -434,6 +434,35 @@ An API is as good as the accompanying documentation. The documentation has to be
</dl>
</div>

<div class="rule" id="/core/doc-openapi-contact" data-type="functional">
<p class="rulelab">Document contact information for publicly available APIs</p>
<dl>
<dt>Statement</dt>
<dd>
OpenAPI definition document SHOULD include the <a href="https://spec.openapis.org/oas/v3.0.1.html#contact-object"><code>info.contact</code></a> object for publicly available APIs. Contact information SHOULD NOT be a generic contact address for the whole organisation.
</dd>
<dt>Rationale</dt>
<dd>
The OpenAPI Specification (OAS) [[OPENAPIS]] can include contact information to make clear how to reach out to API owners in case of issues or questions. This is relevant for publicly available APIs (such as OData) where no pre-existing communication channel exists between provider and consumer of the API. For internal APIs (where communication channels such as chat or issue trackers are likely already known), the <code>info.contact</code> MAY be provided.
<div class="example">
<p>Relevant contact information can include an email address and issue tracker.</p>
<pre><code class="json">{
"name": "Gebouwen API beheerder",
"url": "https://www.github.com/ministerie/gebouwen/issues",
"email": "teamgebouwen@ministerie.nl"
}</code></pre>
</div>
</dd>
<dt>Implications</dt>
<dd>
This rule can be tested automatically and an example of the test is included in the automatic tests on <a href="https://developer.overheid.nl/">developer.overheid.nl</a>. The specific tests are published in the [[ADR-Validator]] repository.
</dd>
<dt>How to test</dt>
<dd>
</dd>
</dl>
</div>

<span id="api-17"></span>
<div class="rule" id="/core/doc-language" data-type="functional">
<p class="rulelab">Publish documentation in Dutch unless there is existing documentation in English</p>
Expand Down