ybelenko/oauth2_as_oas3_components

OAuth2 definitions as OpenAPI Spec 3.0 components

1.0.1 2021-04-20 20:45 UTC

MIT

• Yuriy Belenko

• oauth2
• components
• openapi
• oas3

README

The example file which describes OAuth2 token endpoints located dist/oauth2_endpoints.yml.

Why this package exists

Since RFC 6749 OAuth2 server implementation may be very different(optional/recommended response fields, extended grant) it might me useful to describe your unique implementation within your OAS3 file. It's also very handy to see examples of your token and error response, because RFC6749 is a text document without any pictures or graphs. The example file mentioned before contains description of token endpoints for each authorization grant, consider it as starting point.

Example file omits authorization endpoint endpoint on purpose. I don't know how to describe it with OAS3 since endpoint response isn't JSON(html page). If you have any suggestion please submit an issue to this repo.

Since RFC 6749 - The OAuth2.0 Authorization Framework - 2.3.1. Client Password doesn't recommend to send client password in request body then our example expects basic authorization in all endpoints.

Installation

Copy Paste

Since it's not actually a code, but markup you can just copy anything you want from dist/oauth2_endpoints.yml.

There is also enhanced example with polymorphism at dist/oauth2_endpoints_polymorphism.yml. Please, make sure that your tools supports polymorphism. This example contains new features not highly adopted yet. Check at least oneOf property support. I wouldn't use it myself because most of the OpenAPI tools have issues with polymorphism now, but this example may be useful in forseeable future.

Composer

Install Composer - Dependency Manager for PHP

Then run in terminal:

composer require ybelenko/oauth2_as_oas3_components

Use provided components via $ref attribute like:

paths:
  /token:
    post:
      summary: Obtain access token with "authorization_code" grant.
      requestBody:
        $ref: './vendor/ybelenko/oauth2_as_oas3_components/dist/components/requestBodies/TokenRequestCodeGrant.yml'
      responses:
        '200':
          $ref: './vendor/ybelenko/oauth2_as_oas3_components/dist/components/responses/OAuth2TokenSuccessResponse.yml'
        '4XX':
          $ref: './vendor/ybelenko/oauth2_as_oas3_components/dist/components/responses/OAuth2TokenErrorResponse.yml'

Extended example with refs dist/oauth2_endpoints_with_refs.yml

NPM

Install NPM and Node.js

Then run in terminal:

npm i --save oauth2_as_oas3_components

Use provided components via $ref attribute like:

paths:
  /token:
    post:
      summary: Obtain access token with "authorization_code" grant.
      requestBody:
        $ref: './node_modules/oauth2_as_oas3_components/dist/components/requestBodies/TokenRequestCodeGrant.yml'
      responses:
        '200':
          $ref: './node_modules/oauth2_as_oas3_components/dist/components/responses/OAuth2TokenSuccessResponse.yml'
        '4XX':
          $ref: './node_modules/oauth2_as_oas3_components/dist/components/responses/OAuth2TokenErrorResponse.yml'

Extended example with refs dist/oauth2_endpoints_with_refs.yml

Contributing

If you have any suggestions please submit an issue.

License

MIT License