View Source Specification Extensions
Oasis be with the following specification extensions to accommodate some use cases in the defined YAML or JSON specification file.
module-name-space
Module Name Space
"x-oasis-name-space"
, optional, use this field to define the generated Elixir module's name space in the following objects, defaults to Oasis.Gen
:
example
Example
In Paths Object
Here, define this field in Paths Object as a global name space to the all generated modules meanwhile no other special definitions, in the below example there will use "Hello.Petstore" to the module naming prefix alias of the all generated modules.
paths:
/pets:
get:
...
/pets/{id}:
get:
...
delete:
...
x-oasis-name-space: Hello.Petstore
In Operation Object
Here, define this field in Operation Object,
it only affect to a operation related generated modules meanwhile no other special definitions, in the below example
there will use "Petstore.Api" to the module naming prefix alias of the generated related modules to handler request of "/pets" in HTTP GET verb, other generated modules
will use Oasis.Gen
as the default.
paths:
/pets:
get:
x-oasis-name-space: Petstore.Api
operationId: list pets
...
/pets/{id}:
get:
...
delete:
...
In Security Scheme Object
Here, define this field in Security Scheme Object, it only affect to the generated bearer token module meanwhile no other special definitions, in the below example there will use "Petstore.MyToken" to the "helloBearerAuth" module (its full module name is "Petstore.MyToken.HelloBearerAuth").
paths:
/pets:
get:
security:
- helloBearerAuth: []
components:
securitySchemes:
helloBearerAuth: # arbitrary name for the security scheme
scheme: bearer
type: http
x-oasis-name-space: Petstore.MyToken
summary
Summary
"x-oasis-name-space"
can be used at the same time for the above scenarios, but the defined in Security Scheme Object will override the defined in Operation Object for
the generated bearer token module, the defined in Operation Object will override the defined in Paths Object for the corresponding operation related modules.
We also can set a global name space when run mix oas.gen.plug
with the --name-space
argument, it applies to all generated modules and always override the defined from
the specification file.
Follow Elixir's module naming conventions, each dot(".") of module name will split the alias as a directory in lowercase to concat the full directory path, and also we do not validate the value of this field in a strict mode, so please follow the usual naming conventions as much as possible.
router-module-alias
Router Module Alias
"x-oasis-router"
, optional, use this field to define the generated Elixir router module's alias in Paths Object, defaults to Router
.
example-1
Example
When use an OpenAPI Specification to run mix oas.gen.plug
, there will generate a router file and some corresponding operation handler modules files(in pair),
the router file packages all defined HTTP router(s) to each hanlder(s), we can custom the module name of the router file by the "x-oasis-router"
and
"x-oasis-name-space"
in the specification file, without other special name space defined, the following example defines the module full name space of the router
module is "Oasis.Gen.HelloRouter".
paths:
/pets:
..
/pets/{id}:
..
x-oasis-router: HelloRouter
summary-1
Summary
We also can set a router name when run mix oas.gen.plug
with the --router
argument, it applies to the router module and always override the defined from the specification file.
Follow Elixir's module naming conventions, each dot(".") of module name will split the alias as a directory in lowercase to concat the full directory path, and also we do not validate the value of this field in a strict mode, so please follow the usual naming conventions as much as possible.
save-data-from-bearer-token
Save Data from Bearer Token
"x-oasis-key-to-assigns"
, optional, after the verification of the token, the original data will be stored into this provided field (as an atom) of the conn.assigns
for the next accessing, if not defined it, there won't do any process for the verified original data, please see Oasis.Plug.BearerAuth
for details.
example-2
Example
Once the input token is verified, we can access the original data(decrypted from token) via conn.assigns.user_id
in the next plug's pipeline.
openapi: 3.1.0
components:
securitySchemes:
bearerAuth: # arbitrary name for the security scheme
type: http
scheme: bearer
bearerFormat: JWT
x-oasis-key-to-assigns: user_id
paths:
/something:
get:
security:
- bearerAuth: []
signed-headers-for-hamc-authentication
Signed Headers for HAMC Authentication
"x-oasis-signed-headers"
, requried when use HMAC authentication in security
scheme object, this field represents which HTTP header(s) will be used
into signature, please see HMAC-based authentication document for details.