Merge remote-tracking branch 'upstream/master'

Author: tedepstein

IMPLEMENTATIONS.md

@@ -10,6 +10,7 @@ These tools are not endorsed by the OAI.
 |----------------|--------------|----------|---------------------|
 | swagger-parser | [github/swagger-api](https://github.com/swagger-api/swagger-parser) | Java | Swagger 1.0, 1.1, 1.2, 2.0 to OpenAPI Specification converter |
 | swagger-models | [github/swagger-api](https://github.com/swagger-api/swagger-core/tree/master/modules/swagger-models) | Java | OpenAPI 3.0 Java Pojos |
+| springdoc-openapi | [github/springdoc/springdoc-openapi](https://github.com/springdoc/springdoc-openapi) | Java | Library that produces OpenAPI 3.x specification documentation for spring-boot applications.  |
 | KaiZen OpenAPI Parser | [github/RepreZen/KaiZen-OpenAPI-Parser](https://github.com/RepreZen/KaiZen-OpenAPI-Parser) | Java | High-performance Parser, Validator, and Java Object Model for OpenAPI 3.x |
 | openapi3-ts | [github/metadevpro/openapi3-ts](https://github.com/metadevpro/openapi3-ts) | TypeScript | TS Model & utils for OpenAPI 3.0.x contracts |
 | swagger2openapi | [github/mermade/swagger2openapi](https://github.com/mermade/swagger2openapi) | Node.js | An OpenAPI / Swagger 2.0 to OpenAPI 3.0.x converter and validator |
@@ -21,17 +22,22 @@ These tools are not endorsed by the OAI.
 | go-openapi | [github/nasa9084/go-openapi](https://github.com/nasa9084/go-openapi) | Go | Golang struct model for OpenAPI 3.x. |
 | openapi | [github/wzshiming/openapi](https://github.com/wzshiming/openapi) | Go | OpenAPI 3 Specification for golang |
 | kin-openapi | [github/getkin/kin-openapi](https://github.com/getkin/kin-openapi) | Go | OpenAPI 3.x implementation for Go (parsing, converting, validation) |
+| Spectral | [github/stoplightio/spectral](https://github.com/stoplightio/spectral) | TypeScript, JavaScript | A flexible JSON object linter with out of the box support for OpenAPI Specification 2 and 3 |
+| openapi-validator | [gitlab/mmal/openapi-validator](https://gitlab.com/mmalawski/openapi-validator) | PHP | Validates response against OpenAPI schema |
+| OpenAPI-Delphi | [github/paolo-rossi/OpenAPI-Delphi](https://github.com/paolo-rossi/OpenAPI-Delphi) | Delphi | Delphi implementation of a generator, parser and validator for the OpenAPI 3 Specification |
 
 #### Editors
 
 | Title          | Project Link | Language |Description                          |
 |----------------|--------------|----------|---------------------|
+| Visual Studio Code extension | [VS Code marketplace / OpenAPI (Swagger) editor](https://marketplace.visualstudio.com/items?itemName=42Crunch.vscode-openapi) | TypeScript | Extends VS Code to provide OpenAPI 2.0 and 3.0 navigation, code snippets, new API creation |
 | Apicurio Studio | [github/Apicurio/apicurio-studio](https://github.com/Apicurio/apicurio-studio) | Java/TypeScript | Web-Based **visual designer** for OpenAPI 2.0 and 3.0.0. |
 | KaiZen OpenAPI Editor | [github/RepreZen/KaiZen-OpenAPI-Editor](https://github.com/RepreZen/KaiZen-OpenAPI-Editor) | Java | Eclipse Editor for OpenAPI 2.0 and 3.0 |
 | RepreZen API Studio | [RepreZen.com/OpenAPI](https://www.reprezen.com/OpenAPI) | Java | Commercial desktop IDE for API design, documentation & development |
 | OpenAPI-gui | [github/Mermade/openapi-gui](https://github.com/Mermade/openapi-gui) | Node.js | GUI / visual editor for creating and editing OpenAPI definitions |
 | SwaggerHub | [swaggerhub.com](https://swaggerhub.com) | | API Design and Documentation Platform, Built For Teams
 | swagger-editor | [github/swagger-api](https://github.com/swagger-api/swagger-editor) | JavaScript | Web-Based editor for creating, editing, validating and testing OpenAPI\Swagger definitions |
+| Remain OpenAPI Studio | Direct download: https://remainsoftware.com/extranet/download-type/openapi-studio-download <br> Or via Eclipse MarketPlace https://marketplace.eclipse.org/content/openapi-studio-rich-oas3-editor | Java | A user-friendly, visually rich studio supporting all features defined by the OpenAPI 3. Easy but powerful UI-based components creation, API testing, import, export, code generation and much more. |
 
 #### User Interfaces
 
@@ -43,6 +49,7 @@ These tools are not endorsed by the OAI.
 | WebSphere Liberty | [Download jar](https://developer.ibm.com/wasdev/downloads/) | JavaScript | Includes a native OpenAPI v3 UI which allows for customization of its banners and URL |
 | Widdershins | [github/Mermade/widdershins](https://github.com/Mermade/widdershins) | Node.js | Generate Slate/Shins markdown from OpenAPI 3.0.x |
 | angular-swagger-ui | [github/angular-swagger-ui](https://github.com/Orange-OpenSource/angular-swagger-ui) | AngularJS | An angularJS implementation of Swagger UI |
+| Redoc | [github/Redocly/redoc](https://github.com/Redocly/redoc) | JavaScript | A React-based renderer with deep support for OAS v2 and v3 and zero dev-dependency|
 
 #### Mock Servers
 | Title          | Project Link | Language | Description |
@@ -60,6 +67,12 @@ These tools are not endorsed by the OAI.
 | PHP-CRUD-API | [github/mevdschee/php-crud-api](https://github.com/mevdschee/php-crud-api) | PHP | Automatic CRUD API with OpenAPI 3 docs
 | FastAPI | [github/tiangolo/fastapi](https://github.com/tiangolo/fastapi) | Python | OpenAPI 3 based, high performance, Python 3.6+ API framework with automatic data validation, serialization and great editor support.
 
+#### Client Implementations
+
+| Title          | Project Link | Language | Description |
+|----------------|--------------|----------|-------------|
+| Scorpio        | [github/notEthan/scorpio](https://github.com/notEthan/Scorpio) | Ruby | OpenAPI 2 and 3 implementation offering a HTTP client library |
+
 #### Code Generators
 
 | Title          | Project Link | Language |Description                          |
@@ -72,3 +85,5 @@ These tools are not endorsed by the OAI.
 | slush-vertx | [github/pmlopes/slush-vertx](https://github.com/pmlopes/slush-vertx) | Java, Kotlin & Groovy | Generate server skeleton for [Vert.x Web API Contract](http://vertx.io/docs/#web) and API Client based on [Vert.x 3 Web Client](http://vertx.io/docs/#web)
 | WebSphere Liberty | [Download jar](https://developer.ibm.com/wasdev/downloads/) | Java EE | Generates OpenAPI v3 documentation from Java EE applications |
 | swagger-node-codegen | [github/fmvilas/swagger-node-codegen](https://github.com/fmvilas/swagger-node-codegen) | Node.js | Generates a Node.js/express server, but also has a template engine for creating any templates needed. |
+.NET-C#-Annotations | [github/Microsoft/OpenAPI-NET-CSharpAnnotations](https://github.com/Microsoft/OpenAPI.NET.CSharpAnnotations) | dotnet | Convert your native C# comments/annotation XML from your API code into a OpenAPI document object. |
+| Object Oriented OpenAPI Specification | [github/goldspecdigital/oooas](https://github.com/goldspecdigital/oooas) | PHP | Generates OpenAPI documents using PHP. |

TOB.md

@@ -0,0 +1,21 @@
+# Technical Oversight Board ("TOB")
+
+## Description: 
+> The TOB is responsible for managing conflicts, violations of procedures or guidelines or other issues that cannot be resolved in the TSC for the OAS. For further details please consult the OpenAPI Project Charter.
+
+## TSC Elected - terms through May 2021
+Isabelle Mauny @isamauny
+
+Uri Sarid @usarid
+
+Marsh Gardiner @earth2marsh 
+
+Ron Ratovsky @webron
+
+## BGB Elected - terms through May 2020
+
+Darrel Miller @darrelmiller
+
+Jerome Louvel @jlouvel
+
+Jeremy Whitlock @whitlockjc

examples/v2.0/yaml/petstore-expanded.yaml

@@ -113,12 +113,14 @@ definitions:
       - $ref: '#/definitions/NewPet'
       - required:
         - id
+        type: "object"
         properties:
           id:
             type: integer
             format: int64
 
   NewPet:
+    type: "object"
     required:
       - name  
     properties:
@@ -128,6 +130,7 @@ definitions:
         type: string    
 
   Error:
+    type: "object"
     required:
       - code
       - message

examples/v2.0/yaml/petstore.yaml

@@ -74,6 +74,7 @@ paths:
             $ref: '#/definitions/Error'
 definitions:
   Pet:
+    type: "object"
     required:
       - id
       - name
@@ -90,6 +91,7 @@ definitions:
     items:
       $ref: '#/definitions/Pet'
   Error:
+    type: "object"
     required:
       - code
       - message

examples/v3.0/callback-example.yaml

@@ -43,6 +43,7 @@ paths:
                 content:
                   application/json:
                     schema:
+                      type: object
                       properties:
                         timestamp:
                           type: string

examples/v3.0/petstore-expanded.yaml

@@ -127,14 +127,16 @@ components:
     Pet:
       allOf:
         - $ref: '#/components/schemas/NewPet'
-        - required:
+        - type: object
+          required:
           - id
           properties:
             id:
               type: integer
               format: int64
 
     NewPet:
+      type: object
       required:
         - name  
       properties:
@@ -144,6 +146,7 @@ components:
           type: string    
 
     Error:
+      type: object
       required:
         - code
         - message

examples/v3.0/petstore.yaml

@@ -72,7 +72,7 @@ paths:
           content:
             application/json:
               schema:
-                $ref: "#/components/schemas/Pets"
+                $ref: "#/components/schemas/Pet"
         default:
           description: unexpected error
           content:
@@ -82,6 +82,7 @@ paths:
 components:
   schemas:
     Pet:
+      type: object
       required:
         - id
         - name
@@ -98,6 +99,7 @@ components:
       items:
         $ref: "#/components/schemas/Pet"
     Error:
+      type: object
       required:
         - code
         - message

proposals/000_OAS-proposal-template.md

@@ -0,0 +1,44 @@
+# Feature name
+
+
+## Metadata
+
+|Tag |Value |
+|---- | ---------------- |
+|Proposal |[NNNN](https://github.com/OAI/OpenAPI-Specification/tree/master/proposals/{directory_or_file_name})|
+|Authors|[Author 1](https://github.com/{author1}), [Author 2](https://github.com/{author2})|
+|Review Manager |TBD |
+|Status |Proposal, Draft, Promoted, or Abandoned|
+|Implementations |[Click Here](https://github.com/OAI/OpenAPI-Specification/tree/master/proposals/{NNNN}/implementations.md)|
+|Issues |[{issueid}](https://github.com/OAI/OpenAPI-Specification/issues/{Issueid})|
+|Previous Revisions |[{revid}](https://github.com/OAI/OpenAPI-Specification/pull/{revid}) |
+
+.Change Log
+
+|Date |Responsible Party |Description |
+|---- | ---------------- | ---------- |
+
+## Introduction
+
+A short description of what the feature is. Try to keep it to a single-paragraph "elevator pitch" so the reader understands what problem this proposal is addressing.
+
+## Motivation
+
+Describe the problems that this proposal seeks to address. If the problem is that some common pattern is currently hard to express, show how one can currently get a similar effect and describe its drawbacks. If it's completely new functionality that cannot be emulated, motivate why this new functionality would help OpenAPI developers create better code.
+
+## Proposed solution
+
+Describe your solution to the problem. Provide examples and describe how they work. Show how your solution is better than current workarounds: is it cleaner, safer, or more efficient?
+
+## Detailed design
+
+Describe the design of the solution in detail. This should include an exact description of the changes to the contents of the OpenAPI specification. That description should include a extract of each section of the OpenAPI specification which is impacted by the proposal with all proposed modifications applied. These extracts may be provided through additional files which are identified and described in this section.
+
+## Backwards compatibility
+
+Proposals should be structure so that they can be handled by existing OAS compliant software. Any potential issues should be identified and discussed.
+
+## Alternatives considered
+
+Describe alternative approaches to addressing the same problem, and why you chose this approach instead.
+

proposals/001_Alternative Schema Proposal.md

@@ -0,0 +1,73 @@
+# Alternative Schema
+
+## Metadata
+
+|Tag |Value |
+|---- | ---------------- |
+|Proposal |[Alternative Schema](https://github.com/OAI/OpenAPI-Specification/tree/master/proposals/Alternative%20Schema)|
+|Authors|[Chuck Heazel](https://github.com/{cmheazel})|
+|Review Manager |TBD |
+|Status |**Draft** |
+|Implementations |[Click Here](https://github.com/OAI/OpenAPI-Specification/tree/master/proposals/Alternative%20Schema/implementations.md)
+|Issues |[1532](https://github.com/OAI/OpenAPI-Specification/issues/1532)|
+|Previous Revisions |[March 15](https://github.com/OAI/OpenAPI-Specification/pull/1868#issue-261689900) |
+ 
+.Change Log
+
+|Date |Responsible Party |Description |
+|---- | ---------------- | ---------- |
+|3/15/19 |C. Heazel|Initial Markup Draft |
+|4/17/19 |C. Heazel|Re-structured based on Apple Swift|
+
+## Introduction
+
+This a proposal to add a new field called ``alternativeSchema`` to the OAS.
+
+## Motivation
+
+OpenAPI allows APIs to describe the syntax of their request and response messaged using a JSON Schema-like syntax. However, not all messages will be in JSON. The ability to refer to one or more external schema will allow an API to describe the syntax of a message regardless of the format used.
+
+For example: Some XML payloads are defined by an XML schema (the syntax) and a suite of Schematron rules (valid values). JSON Schema cannot effectively represent their content. By providing access to the appropriate appropriate XML Schema and Schematron files, the payload can be validated the way it was intended to be.
+
+## Proposed solution
+
+This proposal makes the following changes to the OAS 3.0 specification:
+
+1. Extend the Schema Object by the addition of the x-oas-draft-alternativeSchema field.
+1. Addition of the Alternative Schema Object.
+1. Addition of Alternative Schema examples.
+1. Addition of a preliminary discussion of the Alternative Schema registry.
+
+## Detailed design
+
+###  Extend the Schema Object 
+
+The OpenAPI Schema Object is extended by the addition of the x-oas-draft-alternativeSchema field. The proposed changes to the OpenAPI specification are provided in [schema_object.md](https://github.com/OAI/OpenAPI-Specification/tree/master/proposals/Alternative%20Schema/schema_object.md)
+
+###  Add the Alternative Schema Object 
+
+The new object, the Alternative Schema Object is added to the OpenAPI specification. The proposed changes to the OpenAPI specification are provided in [alternative_schema_object.md](https://github.com/OAI/OpenAPI-Specification/tree/master/proposals/Alternative%20Schema/alternative_schema_object.md)
+
+### Provide Alternative Schema Examples
+Examples of the use of the Alternative Schema capability is added to the OpenAPI specification. The proposed changes to the OpenAPI specification are provided in [alternative_schema_examples.md](https://github.com/OAI/OpenAPI-Specification/tree/master/proposals/Alternative%20Schema/alternative_schema_examples.md)
+
+### Alternative Schema Registry
+
+Values used to populate the Alternative Schema Object are required to come from the Alternative Schema Registry. The preliminary Alternative Schema Registry is located at <https://spec.openapis.org/registries/alternative-schema>.
+
+*** Note this is a placeholder registry. Don't take the values seriously. ***  
+
+Inital contents of the registry will include:
+
+|Name  |Link  |Description | 
+|--- | --- | --- |
+|jsonSchema |TBD  |JSON Schema | |xsdSchema |TBD  |XML Schema |
+
+## Backwards compatibility
+
+This proposal makes use of the extensibility features of OpenAPI. All changes sould appear as extensions and handled accordingly.
+
+## Alternatives considered
+
+Embedding non-JSON content in the OAS document would have imposed an unacceptable burden on tooling. Therefore, an extenal link was prefered. Considerable discussion was held over exactly how the links should be represented in the Schema Object. The selected option should support the greatest number of possible combinations of external schema that can be expressed with the OpenAPI schema language.
+