From 0c5b48b402fdc5c616dcc6d0231473bdbb766c04 Mon Sep 17 00:00:00 2001 From: Ralf Handl Date: Fri, 28 Jun 2024 16:33:07 +0200 Subject: [PATCH 1/2] Mimic current OpenAPI spec layout --- doc/moonwalk.html | 123 ++++++++++++++++++------------- package.json | 5 +- specification/moonwalk-host.html | 20 +++++ specification/moonwalk-source.md | 116 ++++++----------------------- specification/respecConfig.js | 85 +++++++++++++-------- 5 files changed, 172 insertions(+), 177 deletions(-) diff --git a/doc/moonwalk.html b/doc/moonwalk.html index 18661bf..e393496 100644 --- a/doc/moonwalk.html +++ b/doc/moonwalk.html @@ -1,6 +1,6 @@ - +

-

Moonwalk

-

Unofficial Draft

+

Moonwalk

Version 4.0.0-draft

+

Unofficial Draft

More details about this document
Latest published version:
- https://spec.openapis.org/oas/v3.1.0 + https://oai.github.io/sig-moonwalk/moonwalk.html
-
Latest editor's draft:
https://oai.github.io/sig-moonwalk/
-
History:
- Commit history -
+
Latest editor's draft:
https://github.com/OAI/sig-moonwalk/blob/main/specification/moonwalk-source.md
+ @@ -144,62 +161,62 @@

Moonwalk

-
Feedback:
- GitHub OAI/sig-moonwalk - (pull requests, - new issue, - open issues) -
+
Participate
+ GitHub Moonwalk +
+ File a bug +
+ Commit history +
+ Pull requests +
-

- Copyright © - 2024 - the document editors/authors. - Text is available under the - Creative Commons Attribution 4.0 International Public License; additional terms may apply. -

+

© 2024 the Linux Foundation

-
+ + +

Current Status of Document

-

This contents of this document have been gathered from a combination of the 3.1 specification and proposed changes for Moonwalk. None of the content in this document should be considered as product of consensus. This is a working document for the purposes of getting the mechanics of publishing a document in place and beginning to discuss the overall structure of the document.

+

This contents of this document have been gathered from a combination of the 3.1 specification and proposed changes for Moonwalk. None of the content in this document should be considered as product of consensus. This is a working document for the purposes of getting the mechanics of publishing a document in place and beginning to discuss the overall structure of the document.

Abstract

The OpenAPI Specification (OAS) defines a standard, programming language-agnostic interface description for HTTP APIs, 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.

-
+

Conformance

As well as sections marked as non-normative, all authoring guidelines, diagrams, examples, and notes in this specification are non-normative. Everything else in this specification is normative.

-

This document is licensed under The Apache License, Version 2.0.

-
+

This document is licensed under The Apache License, Version 2.0.

+

1. Introduction

2. Definitions

diff --git a/package.json b/package.json index 6ffd183..8855c94 100644 --- a/package.json +++ b/package.json @@ -25,5 +25,8 @@ "OAS", "Swagger", "API" - ] + ], + "scripts": { + "build": "pwsh scripts/Generate.ps1" + } } diff --git a/specification/moonwalk-host.html b/specification/moonwalk-host.html index a80f275..c9a9cae 100644 --- a/specification/moonwalk-host.html +++ b/specification/moonwalk-host.html @@ -8,6 +8,26 @@ + + +

© 2024 the Linux Foundation

+ diff --git a/specification/moonwalk-source.md b/specification/moonwalk-source.md index 382d553..30beaf3 100644 --- a/specification/moonwalk-source.md +++ b/specification/moonwalk-source.md @@ -1,40 +1,19 @@ - -
## Current Status of Document -This contents of this document have been gathered from a combination of the 3.1 specification and proposed changes for Moonwalk. None of the content in this document should be considered as product of consensus. This is a working document for the purposes of getting the mechanics of publishing a document in place and beginning to discuss the overall structure of the document. +This contents of this document have been gathered from a combination of the 3.1 specification and proposed changes for Moonwalk. None of the content in this document should be considered as product of consensus. This is a working document for the purposes of getting the mechanics of publishing a document in place and beginning to discuss the overall structure of the document. +
The OpenAPI Specification (OAS) defines a standard, programming language-agnostic interface description for HTTP APIs, 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. -
- -This document is licensed under [The Apache License, Version 2.0](https://www.apache.org/licenses/LICENSE-2.0.html). - +This document is licensed under [The Apache License, Version 2.0](https://www.apache.org/licenses/LICENSE-2.0.html).
- ## Introduction ## Definitions @@ -53,152 +32,103 @@ This document is licensed under [The Apache License, Version 2.0](https://www.ap ### Data Types - #### Working With Binary Data - ##### Migrating binary descriptions from OAS 3.0 - ### Rich Text Formatting ### Relative References in URIs - ### Relative References in URLs - ### Referencing Imports #### Using Imported Names - #### Referencing a Complete Document - #### Locating and Loading Imported Resources - #### Security Considerations for URL Retrieval - - ### Specification Extensions - ## Document Processing #### Parsing Documents - #### Structural Interoperability - #### Resolving Implicit Connections - #### Undefined and Implementation-Defined Behavior - - ## OpenAPI Document Structure - ##### General Fixed Fields - #### Info Object - ##### Fixed Fields {#info-object-fixed-fields} - ##### Info Object Example - #### Contact Object - ##### Fixed Fields - ##### Contact Object Example - #### License Object - ##### Fixed Fields - ##### License Object Example - #### Components Object - #### Import Object ##### Fixed Fields - - ### API Shape - ##### Shape Fixed Fields - #### Operation Object - ##### Fixed Fields - ##### Operation Object Example - - ### API Deployment - ##### Deployment Fixed Fields - ##### Deployment Example - #### Deployment Object ##### Deployment Fixed Fields - #### Security Scheme Object - ##### Fixed Fields #### Credential Object - ##### Field Fields - #### Security Config Object ##### ApiKey Config Object - ##### OAuth2 Config Object +##### OIDC Config Object - ##### OIDC Config Object - - - ##### HTTP Config Object - - - +##### HTTP Config Object ## Appendix @@ -206,26 +136,26 @@ This document is licensed under [The Apache License, Version 2.0](https://www.ap ## Revision History -Version | Date | Notes ---- | --- | --- -3.1.0 | 2021-02-15 | Release of the OpenAPI Specification 3.1.0 -3.1.0-rc1 | 2020-10-08 | rc1 of the 3.1 specification -3.1.0-rc0 | 2020-06-18 | rc0 of the 3.1 specification -3.0.3 | 2020-02-20 | Patch release of the OpenAPI Specification 3.0.3 -3.0.2 | 2018-10-08 | Patch release of the OpenAPI Specification 3.0.2 -3.0.1 | 2017-12-06 | Patch release of the OpenAPI Specification 3.0.1 -3.0.0 | 2017-07-26 | Release of the OpenAPI Specification 3.0.0 -3.0.0-rc2 | 2017-06-16 | rc2 of the 3.0 specification -3.0.0-rc1 | 2017-04-27 | rc1 of the 3.0 specification -3.0.0-rc0 | 2017-02-28 | Implementer's Draft of the 3.0 specification -2.0 | 2015-12-31 | Donation of Swagger 2.0 to the OpenAPI Initiative -2.0 | 2014-09-08 | Release of Swagger 2.0 -1.2 | 2014-03-14 | Initial release of the formal document. -1.1 | 2012-08-22 | Release of Swagger 1.1 -1.0 | 2011-08-10 | First release of the Swagger Specification +| Version | Date | Notes | +| --------- | ---------- | ------------------------------------------------- | +| 3.1.0 | 2021-02-15 | Release of the OpenAPI Specification 3.1.0 | +| 3.1.0-rc1 | 2020-10-08 | rc1 of the 3.1 specification | +| 3.1.0-rc0 | 2020-06-18 | rc0 of the 3.1 specification | +| 3.0.3 | 2020-02-20 | Patch release of the OpenAPI Specification 3.0.3 | +| 3.0.2 | 2018-10-08 | Patch release of the OpenAPI Specification 3.0.2 | +| 3.0.1 | 2017-12-06 | Patch release of the OpenAPI Specification 3.0.1 | +| 3.0.0 | 2017-07-26 | Release of the OpenAPI Specification 3.0.0 | +| 3.0.0-rc2 | 2017-06-16 | rc2 of the 3.0 specification | +| 3.0.0-rc1 | 2017-04-27 | rc1 of the 3.0 specification | +| 3.0.0-rc0 | 2017-02-28 | Implementer's Draft of the 3.0 specification | +| 2.0 | 2015-12-31 | Donation of Swagger 2.0 to the OpenAPI Initiative | +| 2.0 | 2014-09-08 | Release of Swagger 2.0 | +| 1.2 | 2014-03-14 | Initial release of the formal document. | +| 1.1 | 2012-08-22 | Release of Swagger 1.1 | +| 1.0 | 2011-08-10 | First release of the Swagger Specification |
-
\ No newline at end of file + diff --git a/specification/respecConfig.js b/specification/respecConfig.js index 17f9c12..c48d1e6 100644 --- a/specification/respecConfig.js +++ b/specification/respecConfig.js @@ -2,34 +2,59 @@ // work with the example here https://github.com/speced/respec/wiki/pre-and-code-elements var respecConfig = { - //preProcess: [loadYaml], - // isPreview: true, - format: "markdown", - noTOC: false, - maxTocLevel: 3, -// additionalCopyrightHolders: "the Linux Foundation", -// includePermalinks: true, - latestVersion: "https://spec.openapis.org/oas/v3.1.0", - github: { - repoURL: "https://github.com/OAI/sig-moonwalk/", - branch: "main" + // preProcess: [loadYaml], + // isPreview: true, + format: "markdown", + // maxTocLevel: 3, + latestVersion: "https://oai.github.io/sig-moonwalk/moonwalk.html", + edDraftURI: + "https://github.com/OAI/sig-moonwalk/blob/main/specification/moonwalk-source.md", + subtitle: "Version 4.0.0-draft", + // publishDate: "yyyy-mm-dd", + logos: [ + { + src: "https://raw.githubusercontent.com/OAI/OpenAPI-Style-Guide/master/graphics/bitmap/OpenAPI_Logo_Pantone.png", + alt: "OpenAPI Initiative", + height: 48, + url: "https://openapis.org/", }, - logos:[{src:"https://raw.githubusercontent.com/OAI/OpenAPI-Style-Guide/master/graphics/bitmap/OpenAPI_Logo_Pantone.png",alt:"OpenAPI Initiative",height:48,url:"https://openapis.org/"}], - specStatus: "unofficial", //Use "unofficial" for unofficial drafts - shortName: "moonwalk-draft", // This should become part of the latestVersion URL - editors: [ - { - name: "TBD" - } - ], - localBiblio: { - "CommonMark": { - "title": "CommonMark syntax", - "href": "https://spec.commonmark.org/", - "status": "Living Standard", - "publisher": "John MacFarlane" - } - } - - } - \ No newline at end of file + ], + specStatus: "unofficial", // Use "unofficial" for unofficial drafts, "base" for official versions + shortName: "moonwalk-draft", // This should become part of the latestVersion URL + editors: [ + { + name: "TBD", + }, + ], + otherLinks: [ + { + key: "Participate", + data: [ + { + value: "GitHub Moonwalk", + href: "https://github.com/OAI/sig-moonwalk/", + }, + { + value: "File a bug", + href: "https://github.com/OAI/sig-moonwalk/issues", + }, + { + value: "Commit history", + href: "https://github.com/OAI/sig-moonwalk/commits/main/specification/moonwalk-source.md", + }, + { + value: "Pull requests", + href: "https://github.com/OAI/sig-moonwalk/pulls", + }, + ], + }, + ], + localBiblio: { + CommonMark: { + title: "CommonMark syntax", + href: "https://spec.commonmark.org/", + status: "Living Standard", + publisher: "John MacFarlane", + }, + }, +}; From b08dcbab3ae06f5c86e8807a1e00f3f511071f21 Mon Sep 17 00:00:00 2001 From: Ralf Handl Date: Mon, 1 Jul 2024 11:36:04 +0200 Subject: [PATCH 2/2] Optional prefix for publishDate --- doc/moonwalk.html | 7 ++++--- specification/moonwalk-host.html | 1 + 2 files changed, 5 insertions(+), 3 deletions(-) diff --git a/doc/moonwalk.html b/doc/moonwalk.html index e393496..aedce29 100644 --- a/doc/moonwalk.html +++ b/doc/moonwalk.html @@ -132,8 +132,8 @@ "publisher": "John MacFarlane" } }, - "publishISODate": "2024-06-28T00:00:00.000Z", - "generatedSubtitle": "Unofficial Draft 28 June 2024" + "publishISODate": "2024-07-01T00:00:00.000Z", + "generatedSubtitle": "Unofficial Draft 01 July 2024" } @@ -141,7 +141,7 @@

Moonwalk

Version 4.0.0-draft

-

Unofficial Draft

+

Unofficial Draft

More details about this document
@@ -195,6 +195,7 @@

Moonwalk

Ve table tr { background-color: #fff; border-top: 1px solid #c6cbd1; } table tr:nth-child(2n) { background-color: #f6f8fa; } pre { background-color: #f6f8fa !important; } + /* .dt-published::before { content: "Published "; } */ /* Uncomment to add "Published" before the publication date */ diff --git a/specification/moonwalk-host.html b/specification/moonwalk-host.html index c9a9cae..9efd913 100644 --- a/specification/moonwalk-host.html +++ b/specification/moonwalk-host.html @@ -24,6 +24,7 @@ table tr { background-color: #fff; border-top: 1px solid #c6cbd1; } table tr:nth-child(2n) { background-color: #f6f8fa; } pre { background-color: #f6f8fa !important; } + /* .dt-published::before { content: "Published "; } */ /* Uncomment to add "Published" before the publication date */

© 2024 the Linux Foundation