-
Notifications
You must be signed in to change notification settings - Fork 8
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Edit/Create - Documentation refactor (#46)
doc: improved documentation
- Loading branch information
1 parent
522a6c5
commit 7d1f12a
Showing
8 changed files
with
520 additions
and
74 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,51 @@ | ||
# API documentation | ||
Services developed with this library automatically also exposes the documentation of the routes and decorators that | ||
are implemented. The documentation is specified using the [OpenAPI 2.0 standard](https://swagger.io/specification/v2/) | ||
and exhibited through [Swagger](https://swagger.io). | ||
|
||
Once the service is started, its documentation can be accessed at | ||
route [`http://localhost:3000/documentation`](http://localhost:3000/documentation). | ||
|
||
The specification of the request scheme | ||
and responses to a route must conform to the format accepted by | ||
[Fastify](https://www.fastify.io/docs/latest/Validation-and-Serialization). | ||
|
||
## Example | ||
```js | ||
const customService = require('@mia-platform/custom-plugin-lib')() | ||
|
||
const schema = { | ||
body: { | ||
type: 'object', | ||
properties: { | ||
someKey: { type: 'string' }, | ||
someOtherKey: { type: 'number' } | ||
} | ||
}, | ||
|
||
querystring: { | ||
name: { type: 'string' }, | ||
excitement: { type: 'integer' } | ||
}, | ||
|
||
params: { | ||
type: 'object', | ||
properties: { | ||
par1: { type: 'string' }, | ||
par2: { type: 'number' } | ||
} | ||
}, | ||
|
||
headers: { | ||
type: 'object', | ||
properties: { | ||
'x-foo': { type: 'string' } | ||
}, | ||
required: ['x-foo'] | ||
} | ||
} | ||
|
||
module.exports = customService(async function exampleService(service) { | ||
service.addRawCustomPlugin('GET', '/endpoint', function handler(request,reply) { ... }, schema) | ||
}) | ||
``` |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,30 @@ | ||
# Custom Service | ||
A Custom Microservice is a service that receives HTTP requests, whose cycle of use and deploy is managed by the platform. A Custom Microservice encapsulates ad-hoc business logics that can be developed by any user of the platform. To know how manage your services in the DevOps Console see the [documentation](https://docs.mia-platform.eu/development_suite/api-console/api-design/services/) | ||
|
||
The library exports a function which creates the infrastructure ready to accept the definition of routes and decorators. | ||
The function optionally can take a schema of the required environment variables (you can find the reference [fastify-env](https://github.com/fastify/fastify-env). | ||
|
||
## Example | ||
|
||
```js | ||
const customService = require('@mia-platform/custom-plugin-lib')({ | ||
type: 'object', | ||
required: ['ENV_VAR'], | ||
properties: { | ||
ENV_VAR: { type: 'string' }, | ||
}, | ||
}) | ||
``` | ||
> **_More examples?_** Go [here](../examples/advanced/index.js#L46) to see another use cases. | ||
You can configure the environment variables from DevOps console, in your service configuration. For further detail see [Mia-Platform documentation](https://docs.mia-platform.eu/development_suite/api-console/api-design/services/#environment-variable-configuration). | ||
|
||
The function expects an async function to initialize and configure the `service`, a [Fastify instance](https://www.fastify.io/docs/latest/Server/). | ||
You can access the environment variables values from `service.config`: | ||
```js | ||
module.exports = customService(async function handler(service) { | ||
const { ENV_VAR } = service.config | ||
... | ||
}) | ||
``` | ||
Upon `service`, you can you can add [routes](Routes.md) and [decorators](Decorators.md). |
Oops, something went wrong.