diff --git a/api.md b/api.md index 0861cf3..ec1eb76 100644 --- a/api.md +++ b/api.md @@ -1,12 +1,12 @@ # The Jolokia Api Server -(Generated by `yarn build-api-doc`.) +(Generated by `yarn build-api-doc`.) > Version 1.0.0-alpha -This document contains a list of currently avaliable apis that +This document contains a list of currently available apis that can be used by the **activemq-artemis-self-provisioning plugin** -to get access to the [management api](https://github.com/apache/activemq-artemis/blob/main/docs/user-manual/management.adoc#the-management-api) of a broker instance via +to get access to the [management api](https://github.com/apache/activemq-artemis/blob/main/docs/user-manual/management.adoc#the-management-api) of a broker instance via its [jolokia](https://jolokia.org/) endpoint. ### How to add new apis to the src @@ -25,12 +25,12 @@ and add a new api definition, for example: - greeting operationId: hello parameters: - - name: name - required: false - in: query - description: The name of a caller - schema: - type: string + - name: name + required: false + in: query + description: The name of a caller + schema: + type: string responses: 200: description: Success @@ -38,7 +38,7 @@ and add a new api definition, for example: application/json: schema: $ref: '#/components/schemas/DummyResponse' - ``` +``` With the above section added, you defined the new api under the path `/hello` and uses http `GET` method. It takes one optional parameter `name` of string @@ -48,14 +48,14 @@ same file. The `operationId` represents the method name that implements the api. Next step is add the implmentation. -Find a place to write your implementation. Your code should be +Find a place to write your implementation. Your code should be placed in the `src/api/controllers` directory. Either create a new `.ts` file or use an existing one. The following code shows a sample implementation: ```typescript - export function hello(req: express.Request, res: express.Response): void { +export function hello(req: express.Request, res: express.Response): void { const name = req.query.name || 'stranger'; const message = `Hello, ${name}!`; res.json({ @@ -79,71 +79,67 @@ see [openapi spec](https://spec.openapis.org/oas/latest.html) After any change to the api, run `yarn codegen` to regenerate the endpoints for the frontend. If necessary update the code that is using the hooks to comply with your changes. - ## Path Table -| Method | Path | Description | -| --- | --- | --- | -| POST | [/jolokia/login](#postjolokialogin) | The login api | -| GET | [/brokers](#getbrokers) | retrieve the broker mbean | -| GET | [/brokerDetails](#getbrokerdetails) | broker details | -| GET | [/readBrokerAttributes](#getreadbrokerattributes) | read broker attributes | -| GET | [/readAddressAttributes](#getreadaddressattributes) | read address attributes | -| GET | [/readQueueAttributes](#getreadqueueattributes) | read queue attributes | -| GET | [/readAcceptorAttributes](#getreadacceptorattributes) | read acceptor attributes | -| GET | [/checkCredentials](#getcheckcredentials) | Check the validity of the credentials | -| POST | [/execBrokerOperation](#postexecbrokeroperation) | execute a broker operation | -| GET | [/brokerComponents](#getbrokercomponents) | list all mbeans | -| GET | [/addresses](#getaddresses) | retrieve all addresses on broker | -| GET | [/queues](#getqueues) | list queues | -| GET | [/queueDetails](#getqueuedetails) | retrieve queue details | -| GET | [/addressDetails](#getaddressdetails) | retrieve address details | -| GET | [/acceptors](#getacceptors) | list acceptors | -| GET | [/acceptorDetails](#getacceptordetails) | retrieve acceptor details | -| GET | [/api-info](#getapi-info) | the api info | +| Method | Path | Description | +| ------ | ----------------------------------------------------- | ------------------------------------- | +| POST | [/jolokia/login](#postjolokialogin) | The login api | +| GET | [/brokers](#getbrokers) | retrieve the broker mbean | +| GET | [/brokerDetails](#getbrokerdetails) | broker details | +| GET | [/readBrokerAttributes](#getreadbrokerattributes) | read broker attributes | +| GET | [/readAddressAttributes](#getreadaddressattributes) | read address attributes | +| GET | [/readQueueAttributes](#getreadqueueattributes) | read queue attributes | +| GET | [/readAcceptorAttributes](#getreadacceptorattributes) | read acceptor attributes | +| GET | [/checkCredentials](#getcheckcredentials) | Check the validity of the credentials | +| POST | [/execBrokerOperation](#postexecbrokeroperation) | execute a broker operation | +| GET | [/brokerComponents](#getbrokercomponents) | list all mbeans | +| GET | [/addresses](#getaddresses) | retrieve all addresses on broker | +| GET | [/queues](#getqueues) | list queues | +| GET | [/queueDetails](#getqueuedetails) | retrieve queue details | +| GET | [/addressDetails](#getaddressdetails) | retrieve address details | +| GET | [/acceptors](#getacceptors) | list acceptors | +| GET | [/acceptorDetails](#getacceptordetails) | retrieve acceptor details | +| GET | [/api-info](#getapi-info) | the api info | ## Reference Table -| Name | Path | Description | -| --- | --- | --- | -| OperationRef | [#/components/schemas/OperationRef](#componentsschemasoperationref) | | -| OperationArgument | [#/components/schemas/OperationArgument](#componentsschemasoperationargument) | | -| OperationResult | [#/components/schemas/OperationResult](#componentsschemasoperationresult) | | -| DummyResponse | [#/components/schemas/DummyResponse](#componentsschemasdummyresponse) | | -| ApiResponse | [#/components/schemas/ApiResponse](#componentsschemasapiresponse) | | -| LoginResponse | [#/components/schemas/LoginResponse](#componentsschemasloginresponse) | | -| Address | [#/components/schemas/Address](#componentsschemasaddress) | | -| Acceptor | [#/components/schemas/Acceptor](#componentsschemasacceptor) | | -| Queue | [#/components/schemas/Queue](#componentsschemasqueue) | | -| Broker | [#/components/schemas/Broker](#componentsschemasbroker) | | -| FailureResponse | [#/components/schemas/FailureResponse](#componentsschemasfailureresponse) | | -| JavaTypes | [#/components/schemas/JavaTypes](#componentsschemasjavatypes) | | -| ComponentDetails | [#/components/schemas/ComponentDetails](#componentsschemascomponentdetails) | | -| Signatures | [#/components/schemas/Signatures](#componentsschemassignatures) | | -| Signature | [#/components/schemas/Signature](#componentsschemassignature) | | -| Attr | [#/components/schemas/Attr](#componentsschemasattr) | | -| Argument | [#/components/schemas/Argument](#componentsschemasargument) | | -| ComponentAttribute | [#/components/schemas/ComponentAttribute](#componentsschemascomponentattribute) | | -| ExecResult | [#/components/schemas/ExecResult](#componentsschemasexecresult) | | +| Name | Path | Description | +| ------------------ | ------------------------------------------------------------------------------- | ----------- | +| OperationRef | [#/components/schemas/OperationRef](#componentsschemasoperationref) | | +| OperationArgument | [#/components/schemas/OperationArgument](#componentsschemasoperationargument) | | +| OperationResult | [#/components/schemas/OperationResult](#componentsschemasoperationresult) | | +| DummyResponse | [#/components/schemas/DummyResponse](#componentsschemasdummyresponse) | | +| ApiResponse | [#/components/schemas/ApiResponse](#componentsschemasapiresponse) | | +| LoginResponse | [#/components/schemas/LoginResponse](#componentsschemasloginresponse) | | +| Address | [#/components/schemas/Address](#componentsschemasaddress) | | +| Acceptor | [#/components/schemas/Acceptor](#componentsschemasacceptor) | | +| Queue | [#/components/schemas/Queue](#componentsschemasqueue) | | +| Broker | [#/components/schemas/Broker](#componentsschemasbroker) | | +| FailureResponse | [#/components/schemas/FailureResponse](#componentsschemasfailureresponse) | | +| JavaTypes | [#/components/schemas/JavaTypes](#componentsschemasjavatypes) | | +| ComponentDetails | [#/components/schemas/ComponentDetails](#componentsschemascomponentdetails) | | +| Signatures | [#/components/schemas/Signatures](#componentsschemassignatures) | | +| Signature | [#/components/schemas/Signature](#componentsschemassignature) | | +| Attr | [#/components/schemas/Attr](#componentsschemasattr) | | +| Argument | [#/components/schemas/Argument](#componentsschemasargument) | | +| ComponentAttribute | [#/components/schemas/ComponentAttribute](#componentsschemascomponentattribute) | | +| ExecResult | [#/components/schemas/ExecResult](#componentsschemasexecresult) | | ## Path Details -*** +--- ### [POST]/jolokia/login - Summary -The login api + The login api - Description -This api is used to login to a jolokia endpoint. It tries to get the broker mbean via the joloia url using the parameters passed in. - + This api is used to login to a jolokia endpoint. It tries to get the broker mbean via the joloia url using the parameters passed in. If it succeeds, it generates a [jwt token](https://jwt.io/introduction) and returns -it back to the client. If it fails it returns a error. - + it back to the client. If it fails it returns a error. Once authenticated, the client can access the -apis defined in this file. With each request the client must include a valid jwt token in a http header named `jolokia-session-id`. The src will validate the token before processing a request is and rejects the request if the token is not valid. - + apis defined in this file. With each request the client must include a valid jwt token in a http header named `jolokia-session-id`. The src will validate the token before processing a request is and rejects the request if the token is not valid. #### RequestBody @@ -152,17 +148,17 @@ apis defined in this file. With each request the client must include a valid jwt ```ts { // identity of the broker instance, must in form of {cr-name}-{pod-ordinal}:{namespace}. For example ex-aao-0:test1 - brokerName: string + brokerName: string; // The user name - userName: string + userName: string; // The password - password: string + password: string; // The host name of the broker - jolokiaHost: string + jolokiaHost: string; // either *http* or *https* - scheme: string + scheme: string; // port number of jolokia endpoint - port: string + port: string; } ``` @@ -203,18 +199,17 @@ apis defined in this file. With each request the client must include a valid jwt } ``` -*** +--- ### [GET]/brokers - Summary -retrieve the broker mbean + retrieve the broker mbean - Description -**Get the broker mbean** - The return value is a one-element array that contains - the broker's mbean object name. - + **Get the broker mbean** + The return value is a one-element array that contains + the broker's mbean object name. #### Headers @@ -230,8 +225,9 @@ jolokia-session-id: string ```ts { - name: string -}[] + name: string; +} +[]; ``` - 401 Invalid credentials @@ -256,19 +252,18 @@ jolokia-session-id: string } ``` -*** +--- ### [GET]/brokerDetails - Summary -broker details + broker details - Description -**Get the broker details** - The return value is a json object that contains - description of all the operations and attributes of the broker's mbean. - It is defined in [ActiveMQServerControl.java](https://github.com/apache/activemq-artemis/blob/2.33.0/artemis-core-client/src/main/java/org/apache/activemq/artemis/api/core/management/ActiveMQServerControl.java) - + **Get the broker details** + The return value is a json object that contains + description of all the operations and attributes of the broker's mbean. + It is defined in [ActiveMQServerControl.java](https://github.com/apache/activemq-artemis/blob/2.33.0/artemis-core-client/src/main/java/org/apache/activemq/artemis/api/core/management/ActiveMQServerControl.java) #### Headers @@ -315,21 +310,19 @@ jolokia-session-id: string } ``` -*** +--- ### [GET]/readBrokerAttributes - Summary -read broker attributes + read broker attributes - Description -**Read values of broker attributes** - The return value is a json array that contains - values of requested attributes of the broker's mbean. - + **Read values of broker attributes** + The return value is a json array that contains + values of requested attributes of the broker's mbean. **Note**: to read multiple attributes, set it to **names** parameter - separated by commas, e.g. `Version,Status`. - + separated by commas, e.g. `Version,Status`. #### Parameters(Query) @@ -385,26 +378,24 @@ jolokia-session-id: string } ``` -*** +--- ### [GET]/readAddressAttributes - Summary -read address attributes + read address attributes - Description -**Read values of address attributes** - The return value is a json array that contains - values of requested attributes of the addresses's mbean. - + **Read values of address attributes** + The return value is a json array that contains + values of requested attributes of the addresses's mbean. **Note**: to read multiple attributes, set it to **attrs** parameter - separated by commas, e.g. `RoutingTypes,Address`. - + separated by commas, e.g. `RoutingTypes,Address`. #### Parameters(Query) ```ts -name: string +name: string; ``` ```ts @@ -459,30 +450,28 @@ jolokia-session-id: string } ``` -*** +--- ### [GET]/readQueueAttributes - Summary -read queue attributes + read queue attributes - Description -**Read values of queue attributes** - The return value is a json array that contains - values of requested attributes of the queue's mbean. - + **Read values of queue attributes** + The return value is a json array that contains + values of requested attributes of the queue's mbean. **Note**: to read multiple attributes, set it to **attrs** parameter - separated by commas, e.g. `RoutingTypes,Address`. - + separated by commas, e.g. `RoutingTypes,Address`. #### Parameters(Query) ```ts -name: string +name: string; ``` ```ts -address: string +address: string; ``` ```ts @@ -541,26 +530,24 @@ jolokia-session-id: string } ``` -*** +--- ### [GET]/readAcceptorAttributes - Summary -read acceptor attributes + read acceptor attributes - Description -**Read values of acceptor attributes** - The return value is a json array that contains - values of requested attributes of the acceptor's mbean. - + **Read values of acceptor attributes** + The return value is a json array that contains + values of requested attributes of the acceptor's mbean. **Note**: to read multiple attributes, set it to **attrs** parameter - separated by commas, e.g. `RoutingTypes,Address`. - + separated by commas, e.g. `RoutingTypes,Address`. #### Parameters(Query) ```ts -name: string +name: string; ``` ```ts @@ -615,12 +602,12 @@ jolokia-session-id: string } ``` -*** +--- ### [GET]/checkCredentials - Summary -Check the validity of the credentials + Check the validity of the credentials #### Headers @@ -663,21 +650,19 @@ jolokia-session-id: string } ``` -*** +--- ### [POST]/execBrokerOperation - Summary -execute a broker operation + execute a broker operation - Description -**Invoke an operation of the broker mbean** - + **Invoke an operation of the broker mbean** It receives a POST request where the body - should have the operation signature and its args. - The return value is a one element json array that contains - return values of invoked operation along with the request info. - + should have the operation signature and its args. + The return value is a one element json array that contains + return values of invoked operation along with the request info. #### Headers @@ -745,19 +730,17 @@ jolokia-session-id: string } ``` -*** +--- ### [GET]/brokerComponents - Summary -list all mbeans + list all mbeans - Description -**List all broker components** - + **List all broker components** It retrieves and returns a list of all mbeans - registered directly under the broker managment domain. - + registered directly under the broker managment domain. #### Headers @@ -797,18 +780,16 @@ string[] } ``` -*** +--- ### [GET]/addresses - Summary -retrieve all addresses on broker + retrieve all addresses on broker - Description -**Get all addresses in a broker** - - It retrieves and returns a list of all address mbeans - + **Get all addresses in a broker** + It retrieves and returns a list of all address mbeans #### Headers @@ -824,11 +805,12 @@ jolokia-session-id: string ```ts { - name: string + name: string; broker: { - name: string + name: string; } -}[] +} +[]; ``` - 401 Invalid credentials @@ -853,18 +835,16 @@ jolokia-session-id: string } ``` -*** +--- ### [GET]/queues - Summary -list queues + list queues - Description -**Get all queues in a broker** - - It retrieves and returns a list of all queue mbeans - + **Get all queues in a broker** + It retrieves and returns a list of all queue mbeans #### Parameters(Query) @@ -921,20 +901,18 @@ jolokia-session-id: string } ``` -*** +--- ### [GET]/queueDetails - Summary -retrieve queue details + retrieve queue details - Description -**Get details of a queue** - The return value is a json object that contains - description of all the operations and attributes of the `queue` mbean. - - It is defined in [QueueControl.java](https://github.com/apache/activemq-artemis/blob/2.33.0/artemis-core-client/src/main/java/org/apache/activemq/artemis/api/core/management/QueueControl.java) - + **Get details of a queue** + The return value is a json object that contains + description of all the operations and attributes of the `queue` mbean. + It is defined in [QueueControl.java](https://github.com/apache/activemq-artemis/blob/2.33.0/artemis-core-client/src/main/java/org/apache/activemq/artemis/api/core/management/QueueControl.java) #### Parameters(Query) @@ -945,12 +923,12 @@ addressName?: string ```ts // the name of the queue -name: string +name: string; ``` ```ts // the routing type of the queue (anycast or multicast) -routingType: string +routingType: string; ``` #### Headers @@ -998,26 +976,24 @@ jolokia-session-id: string } ``` -*** +--- ### [GET]/addressDetails - Summary -retrieve address details + retrieve address details - Description -**Get details of an address** - The return value is a json object that contains - description of all the operations and attributes of the address mbean. - - It is defined in [AddressControl.java](https://github.com/apache/activemq-artemis/blob/2.33.0/artemis-core-client/src/main/java/org/apache/activemq/artemis/api/core/management/AddressControl.java) - + **Get details of an address** + The return value is a json object that contains + description of all the operations and attributes of the address mbean. + It is defined in [AddressControl.java](https://github.com/apache/activemq-artemis/blob/2.33.0/artemis-core-client/src/main/java/org/apache/activemq/artemis/api/core/management/AddressControl.java) #### Parameters(Query) ```ts // the address name -name: string +name: string; ``` #### Headers @@ -1065,18 +1041,16 @@ jolokia-session-id: string } ``` -*** +--- ### [GET]/acceptors - Summary -list acceptors + list acceptors - Description -**Get all acceptors in a broker** - - It retrieves and returns a list of all acceptor mbeans - + **Get all acceptors in a broker** + It retrieves and returns a list of all acceptor mbeans #### Headers @@ -1092,11 +1066,12 @@ jolokia-session-id: string ```ts { - name: string + name: string; broker: { - name: string + name: string; } -}[] +} +[]; ``` - 401 Invalid credentials @@ -1121,26 +1096,24 @@ jolokia-session-id: string } ``` -*** +--- ### [GET]/acceptorDetails - Summary -retrieve acceptor details + retrieve acceptor details - Description -**Get details of an acceptor** - The return value is a json object that contains - description of all the operations and attributes of an `acceptor` mbean. - - It is defined in [AcceptorControl.java](https://github.com/apache/activemq-artemis/blob/2.33.0/artemis-core-client/src/main/java/org/apache/activemq/artemis/api/core/management/AcceptorControl.java) - + **Get details of an acceptor** + The return value is a json object that contains + description of all the operations and attributes of an `acceptor` mbean. + It is defined in [AcceptorControl.java](https://github.com/apache/activemq-artemis/blob/2.33.0/artemis-core-client/src/main/java/org/apache/activemq/artemis/api/core/management/AcceptorControl.java) #### Parameters(Query) ```ts // the acceptor name -name: string +name: string; ``` #### Headers @@ -1188,19 +1161,17 @@ jolokia-session-id: string } ``` -*** +--- ### [GET]/api-info - Summary -the api info + the api info - Description -**Show all exposed paths on the api server** - + **Show all exposed paths on the api server** The return value is a json object that contains - description of all api paths defined in the api server. - + description of all api paths defined in the api server. #### Responses @@ -1314,9 +1285,9 @@ the api info ```ts { - name: string + name: string; broker: { - name: string + name: string; } } ``` @@ -1325,9 +1296,9 @@ the api info ```ts { - name: string + name: string; broker: { - name: string + name: string; } } ``` @@ -1352,7 +1323,7 @@ the api info ```ts { - name: string + name: string; } ``` @@ -1483,4 +1454,4 @@ the api info timestamp?: number status: number } -``` \ No newline at end of file +``` diff --git a/src/config/openapi.yml b/src/config/openapi.yml index f14bb42..515e6f8 100644 --- a/src/config/openapi.yml +++ b/src/config/openapi.yml @@ -8,7 +8,7 @@ info: url: https://www.apache.org/licenses/LICENSE-2.0 version: 1.0.0-alpha description: | - This document contains a list of currently avaliable apis that + This document contains a list of currently available apis that can be used by the **activemq-artemis-self-provisioning plugin** to get access to the [management api](https://github.com/apache/activemq-artemis/blob/main/docs/user-manual/management.adoc#the-management-api) of a broker instance via its [jolokia](https://jolokia.org/) endpoint.