Skip to content

Commit c8a9466

Browse files
nickevansuknickevansuk
committed
fix: Documentation and CI
1 parent 9b70d86 commit c8a9466

5 files changed

Lines changed: 64 additions & 35 deletions

File tree

‎.github/workflows/create-data-model-pr.yaml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -46,7 +46,7 @@ jobs:
4646
# - The dataset-site-template version number updating within the template in DatasetSiteMustacheTemplate.cs (affects one line)
4747
# - Any updates to the package.json or package-lock.json files in OpenActive.DatasetSite.NET.Generator (not worth creating a PR JUST for these if the new version did not have any implications)
4848
# git stashing if no material changes allows the next step to close the PR if one is already open
49-
run: if [ "$(git diff --numstat | grep -vc '^1.*DatasetSiteMustacheTemplate\.cs\|.*package\.json\|.*package-lock\.json$')" -eq "0" ]; then git stash; else echo "Material changes found"; fi
49+
run: if [ "$(git diff --numstat | grep -vc '^1 .*DatasetSiteMustacheTemplate\.cs\|.*package\.json\|.*package-lock\.json$')" -eq "0" ]; then git stash; else echo "Material changes found"; fi
5050
working-directory: ./
5151

5252
- name: Create Pull Request

‎OpenActive.DatasetSite.NET.Tests/SimpleImplementation.cs‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -25,15 +25,15 @@ public void SettingsContainedInRenderedPage()
2525
{
2626
OpenDataFeedBaseUrl = "https://customer.example.com/feed".ParseUrlOrNull(),
2727
OpenBookingAPIBaseUrl = "https://customer.example.com/api/openbooking".ParseUrlOrNull(),
28-
OpenBookingAPIAuthenticationAuthority = "https://auth.acmebooker.example.com".ParseUrlOrNull(),
28+
OpenBookingAPIAuthenticationAuthorityUrl = "https://auth.acmebooker.example.com".ParseUrlOrNull(),
2929
DatasetSiteUrl = "https://halo-odi.legendonlineservices.co.uk/openactive/".ParseUrlOrNull(),
3030
DatasetDiscussionUrl = "https://github.com/gll-better/opendata".ParseUrlOrNull(),
3131
DatasetDocumentationUrl = "https://docs.acmebooker.example.com/".ParseUrlOrNull(),
3232
DatasetLanguages = new List<string> { "en-GB" },
3333
OrganisationName = "Better",
3434
OrganisationUrl = "https://www.better.org.uk/".ParseUrlOrNull(),
3535
OrganisationLegalEntity = "GLL",
36-
OrganisationPlainTextDescription = "Established in 1993, GLL is the largest UK-based charitable social enterprise delivering leisure, health and community services. Under the consumer facing brand Better, we operate 258 public Sports and Leisure facilities, 88 libraries, 10 children’s centres and 5 adventure playgrounds in partnership with 50 local councils, public agencies and sporting organisations. Better leisure facilities enjoy 46 million visitors a year and have more than 650,000 members.",
36+
OrganisationPlainTextDescription = "Established in 1993, GLL is the largest UK-based charitable social enterprise delivering leisure, health and community services. Under the consumer facing brand Better, we operate 258 public Sports and Leisure facilities, 88 libraries, 10 children�s centres and 5 adventure playgrounds in partnership with 50 local councils, public agencies and sporting organisations. Better leisure facilities enjoy 46 million visitors a year and have more than 650,000 members.",
3737
OrganisationLogoUrl = "http://data.better.org.uk/images/logo.png".ParseUrlOrNull(),
3838
OrganisationEmail = "info@better.org.uk",
3939
PlatformName = "AcmeBooker",

‎OpenActive.DatasetSite.NET/DatasetSiteGenerator.cs‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -140,7 +140,7 @@ public static string RenderSimpleDatasetSiteFromDataDownloads(DatasetSiteGenerat
140140
Documentation = settings.OpenBookingAPIDocumentationUrl ?? new Uri("https://developer.openactive.io/go/open-booking-api"),
141141
TermsOfService = settings.OpenBookingAPITermsOfServiceUrl,
142142
EndpointUrl = settings.OpenBookingAPIBaseUrl,
143-
AuthenticationAuthority = settings.OpenBookingAPIAuthenticationAuthority,
143+
AuthenticationAuthority = settings.OpenBookingAPIAuthenticationAuthorityUrl,
144144
ConformsTo = new List<Uri> { new Uri("https://openactive.io/open-booking-api/EditorsDraft/") },
145145
EndpointDescription = new Uri("https://www.openactive.io/open-booking-api/EditorsDraft/swagger.json"),
146146
LandingPage = settings.OpenBookingAPIRegistrationUrl

‎OpenActive.DatasetSite.NET/models/DatasetSiteGeneratorSettings.cs‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -112,7 +112,7 @@ public class DatasetSiteGeneratorSettings
112112
/// <summary>
113113
/// The Issuer URL of the OpenID Provider used to access the Open Booking API
114114
/// </summary>
115-
public Uri OpenBookingAPIAuthenticationAuthority { get; set; }
115+
public Uri OpenBookingAPIAuthenticationAuthorityUrl { get; set; }
116116

117117
/// <summary>
118118
/// The publicly accessible URL of an up-to-date OpenActive Test Suite Certificate for the implementation

‎README.md‎

Lines changed: 59 additions & 30 deletions
Original file line numberDiff line numberDiff line change
@@ -40,26 +40,30 @@ Returns a string corresponding to the compiled HTML, based on an embedded versio
4040

4141
#### DatasetSiteGeneratorSettings
4242

43-
| Property | Type | Description |
44-
| ---------------------------------- | -------- | ----------- |
45-
| `OpenDataFeedBaseUrl` | `Uri` | The base URL for the open data feeds (must not contain trailing `/`) |
46-
| `DatasetSiteUrl` | `Uri` | The URL where this dataset site is displayed (the page's own URL) |
47-
| `DatasetDiscussionUrl` | `Uri` | The GitHub issues page for the dataset |
48-
| `DatasetDocumentationUrl` | `Uri` | Any documentation specific to the dataset. Defaults to https://developer.openactive.io/ if not provided, which should be used if no documentation is available. |
49-
| `DatasetLanguages` | `List<string>` | The languages available in the dataset, following the IETF BCP 47 standard. Defaults to 'en-GB'. |
50-
| `OrganisationName` | `string` | The publishing organisation's name |
51-
| `OrganisationUrl` | `Uri` | The publishing organisation's URL |
52-
| `OrganisationLegalEntity` | `string` | The legal name of the publishing organisation of this dataset |
53-
| `OrganisationPlainTextDescription` | `string` | A plain text description of this organisation |
54-
| `OrganisationLogoUrl` | `Uri` | An image URL of the publishing organisation's logo, ideally in PNG format |
55-
| `OrganisationEmail` | `string` | The contact email of the publishing organisation of this dataset |
56-
| `PlatformName` | `string` | The software platform's name. Only set this if different from the publishing organisation, otherwise leave as null to exclude platform metadata. |
57-
| `PlatformUrl` | `Uri` | The software platform's website |
58-
| `PlatformSoftwareVersion` | `string` | The software platform's software version |
59-
| `BackgroundImageUrl` | `Uri` | The background image to show on the Dataset Site page |
60-
| `DateFirstPublished` | `DateTimeOffset` | The date the dataset was first published |
61-
62-
43+
| Property | Type | Description |
44+
| -------------------------------------------| -------- | ----------- |
45+
| `OpenDataFeedBaseUrl` | `Uri` | The base URL for the open data feeds (must not contain trailing `/`) |
46+
| `DatasetSiteUrl` | `Uri` | The URL where this dataset site is displayed (the page's own URL) |
47+
| `DatasetDiscussionUrl` | `Uri` | The GitHub issues page for the dataset |
48+
| `DatasetDocumentationUrl` | `Uri` | Any documentation specific to the dataset. Defaults to https://developer.openactive.io/ if not provided, which should be used if no documentation is available . |
49+
| `DatasetLanguages` | `List<string>` | The languages available in the dataset, following the IETF BCP 47 standard. Defaults to 'en-GB'. |
50+
| `OrganisationName` | `string` | The publishing organisation's name |
51+
| `OrganisationUrl` | `Uri` | The publishing organisation's URL |
52+
| `OrganisationLegalEntity` | `string` | The legal name of the publishing organisation of this dataset |
53+
| `OrganisationPlainTextDescription` | `string` | A plain text description of this organisation |
54+
| `OrganisationLogoUrl` | `Uri` | An image URL of the publishing organisation's logo, ideally in PNG format |
55+
| `OrganisationEmail` | `string` | The contact email of the publishing organisation of this dataset |
56+
| `PlatformName` | `string` | The software platform's name. Only set this if different from the publishing organisation, otherwise leave as null to exclude platform metadata. |
57+
| `PlatformUrl` | `Uri` | The software platform's website |
58+
| `PlatformSoftwareVersion` | `string` | The software platform's software version |
59+
| `BackgroundImageUrl` | `Uri` | The background image to show on the Dataset Site page |
60+
| `DateFirstPublished` | `DateTimeOffset` | The date the dataset was first published |
61+
| `OpenBookingAPIBaseUrl` | `Uri` | The Base URI of this implementation of the Open Booking API |
62+
| `OpenBookingAPIAuthenticationAuthorityUrl` | `Uri` | The location of the OpenID Provider that must be used to access the API |
63+
| `OpenBookingAPIDocumentationUrl` | `Uri` | The URL of documentation related to how to use the Open Booking API. Defaults to https://developer.openactive.io/go/open-booking-api if not provided, which should be use if no documentation is available. |
64+
| `OpenBookingAPITermsOfServiceUrl` | `Uri` | The URL of terms of service related to the use of this API |
65+
| `OpenBookingAPIRegistrationUrl` | `Uri` | The URL of a web page that the Broker may use to obtain access to the API, e.g. via a web form |
66+
| `TestSuiteCertificateUrl` | `Uri` | The URL of the OpenActive Test Suite certificate for this booking system |
6367

6468
#### Example
6569

@@ -74,8 +78,6 @@ public class DatasetSiteController : Controller
7478
var settings = new DatasetSiteGeneratorSettings
7579
{
7680
OpenDataFeedBaseUrl = "https://customer.example.com/feed".ParseUrlOrNull(),
77-
OpenBookingAPIBaseUrl = "https://customer.example.com/api/openbooking".ParseUrlOrNull(),
78-
OpenBookingAPIAuthenticationAuthority = "https://auth.acmebooker.example.com/".ParseUrlOrNull(),
7981
DatasetSiteUrl = "https://halo-odi.legendonlineservices.co.uk/openactive/".ParseUrlOrNull(),
8082
DatasetDiscussionUrl = "https://github.com/gll-better/opendata".ParseUrlOrNull(),
8183
DatasetDocumentationUrl = "https://docs.acmebooker.example.com/".ParseUrlOrNull(),
@@ -90,7 +92,13 @@ public class DatasetSiteController : Controller
9092
PlatformUrl = "https://acmebooker.example.com/".ParseUrlOrNull(),
9193
PlatformVersion = "2.0",
9294
BackgroundImageUrl = "https://data.better.org.uk/images/bg.jpg".ParseUrlOrNull(),
93-
DateFirstPublished = new DateTimeOffset(new DateTime(2019, 01, 14))
95+
DateFirstPublished = new DateTimeOffset(new DateTime(2019, 01, 14)),
96+
OpenBookingAPIBaseUrl = "https://reference-implementation.openactive.io/api/openbooking".ParseUrlOrNull(),
97+
OpenBookingAPIAuthenticationAuthorityUrl = "https://auth.reference-implementation.openactive.io".ParseUrlOrNull(),
98+
OpenBookingAPIDocumentationUrl = "https://developer.openactive.io/go/open-booking-api".ParseUrlOrNull(),
99+
OpenBookingAPITermsOfServiceUrl = "https://example.com/api-terms-page".ParseUrlOrNull(),
100+
OpenBookingAPIRegistrationUrl = "https://example.com/api-landing-page".ParseUrlOrNull(),
101+
TestSuiteCertificateUrl = "https://certificates.reference-implementation.openactive.io/examples/all-features/controlled/".ParseUrlOrNull()
94102
};
95103

96104
var supportedFeeds = new List<OpportunityType> {
@@ -136,8 +144,6 @@ public class DatasetSiteController : Controller
136144
var settings = new DatasetSiteGeneratorSettings
137145
{
138146
OpenDataFeedBaseUrl = "https://customer.example.com/feed".ParseUrlOrNull(),
139-
OpenBookingAPIBaseUrl = "https://customer.example.com/api/openbooking".ParseUrlOrNull(),
140-
OpenBookingAPIAuthenticationAuthority = "https://auth.acmebooker.example.com/".ParseUrlOrNull(),
141147
DatasetSiteUrl = "https://halo-odi.legendonlineservices.co.uk/openactive/".ParseUrlOrNull(),
142148
DatasetDiscussionUrl = "https://github.com/gll-better/opendata".ParseUrlOrNull(),
143149
DatasetDocumentationUrl = "https://docs.acmebooker.example.com/".ParseUrlOrNull(),
@@ -152,7 +158,13 @@ public class DatasetSiteController : Controller
152158
PlatformUrl = "https://acmebooker.example.com/".ParseUrlOrNull(),
153159
PlatformVersion = "2.0",
154160
BackgroundImageUrl = "https://data.better.org.uk/images/bg.jpg".ParseUrlOrNull(),
155-
DateFirstPublished = new DateTimeOffset(new DateTime(2019, 01, 14))
161+
DateFirstPublished = new DateTimeOffset(new DateTime(2019, 01, 14)),
162+
OpenBookingAPIBaseUrl = "https://reference-implementation.openactive.io/api/openbooking".ParseUrlOrNull(),
163+
OpenBookingAPIAuthenticationAuthorityUrl = "https://auth.reference-implementation.openactive.io".ParseUrlOrNull(),
164+
OpenBookingAPIDocumentationUrl = "https://developer.openactive.io/go/open-booking-api".ParseUrlOrNull(),
165+
OpenBookingAPITermsOfServiceUrl = "https://example.com/api-terms-page".ParseUrlOrNull(),
166+
OpenBookingAPIRegistrationUrl = "https://example.com/api-landing-page".ParseUrlOrNull(),
167+
TestSuiteCertificateUrl = "https://certificates.reference-implementation.openactive.io/examples/all-features/controlled/".ParseUrlOrNull()
156168
};
157169

158170
var dataDownloads = new List<DataDownload>
@@ -223,8 +235,6 @@ public class DatasetSiteController : Controller
223235
var settings = new DatasetSiteGeneratorSettings
224236
{
225237
OpenDataFeedBaseUrl = "https://customer.example.com/feed".ParseUrlOrNull(),
226-
OpenBookingAPIBaseUrl = "https://customer.example.com/api/openbooking".ParseUrlOrNull(),
227-
OpenBookingAPIAuthenticationAuthority = "https://auth.acmebooker.example.com/".ParseUrlOrNull(),
228238
DatasetSiteUrl = "https://halo-odi.legendonlineservices.co.uk/openactive/".ParseUrlOrNull(),
229239
DatasetDiscussionUrl = "https://github.com/gll-better/opendata".ParseUrlOrNull(),
230240
DatasetDocumentationUrl = "https://docs.acmebooker.example.com/".ParseUrlOrNull(),
@@ -239,7 +249,13 @@ public class DatasetSiteController : Controller
239249
PlatformUrl = "https://acmebooker.example.com/".ParseUrlOrNull(),
240250
PlatformVersion = "2.0",
241251
BackgroundImageUrl = "https://data.better.org.uk/images/bg.jpg".ParseUrlOrNull(),
242-
DateFirstPublished = new DateTimeOffset(new DateTime(2019, 01, 14))
252+
DateFirstPublished = new DateTimeOffset(new DateTime(2019, 01, 14)),
253+
OpenBookingAPIBaseUrl = "https://reference-implementation.openactive.io/api/openbooking".ParseUrlOrNull(),
254+
OpenBookingAPIAuthenticationAuthorityUrl = "https://auth.reference-implementation.openactive.io".ParseUrlOrNull(),
255+
OpenBookingAPIDocumentationUrl = "https://developer.openactive.io/go/open-booking-api".ParseUrlOrNull(),
256+
OpenBookingAPITermsOfServiceUrl = "https://example.com/api-terms-page".ParseUrlOrNull(),
257+
OpenBookingAPIRegistrationUrl = "https://example.com/api-landing-page".ParseUrlOrNull(),
258+
TestSuiteCertificateUrl = "https://certificates.reference-implementation.openactive.io/examples/all-features/controlled/".ParseUrlOrNull()
243259
};
244260

245261
var dataFeedHumanisedList = "Sessions and Facilities";
@@ -320,7 +336,20 @@ public class DatasetSiteController : Controller
320336
{
321337
Name = settings.PlatformName,
322338
Url = settings.PlatformUrl,
323-
SoftwareVersion = settings.PlatformVersion
339+
SoftwareVersion = settings.PlatformVersion,
340+
HasCredential = settings.TestSuiteCertificateUrl
341+
},
342+
AccessService = settings.OpenBookingAPIBaseUrl == null ? null : new WebAPI
343+
{
344+
Name = "Open Booking API",
345+
Description = $"API that allows for seamless booking experiences to be created for {dataFeedHumanisedList.ToLowerInvariant()} available from {settings.OrganisationName}",
346+
Documentation = settings.OpenBookingAPIDocumentationUrl ?? new Uri("https://developer.openactive.io/go/open-booking-api"),
347+
TermsOfService = settings.OpenBookingAPITermsOfServiceUrl,
348+
EndpointUrl = settings.OpenBookingAPIBaseUrl,
349+
AuthenticationAuthority = settings.OpenBookingAPIAuthenticationAuthorityUrl,
350+
ConformsTo = new List<Uri> { new Uri("https://openactive.io/open-booking-api/EditorsDraft/") },
351+
EndpointDescription = new Uri("https://www.openactive.io/open-booking-api/EditorsDraft/swagger.json"),
352+
LandingPage = settings.OpenBookingAPIRegistrationUrl
324353
}
325354
};
326355

0 commit comments

Comments
 (0)