By default, moclojer reads the endpoint.response.body
parameter for the endpoint return, but when we need a “long” return (with lots of characters) the specification file (yaml example) makes it difficult to maintain and leaves it with low visibility (confusing).
To solve this problem you can stop using endpoint.response.body
and use endpoint.response.external-body
which has the following structure:
external-body:
provider: json
path: files-path.json
We support two providers (file type):
json
, with file support (on local disk) or remote via httpxlsx
(excel)it is possible to use template rendering to declare the
path
of the file, see more here.
json
type- endpoint:
method: GET
path: /external-body-text
response:
status: 200
headers:
Content-Type: application/json
external-body:
provider: json
path: test/com/moclojer/resources/text-plan.json
Swagger:
{% swagger method="get" path="/external-body-text" baseUrl="" summary="" %}
{% swagger-description %}
Will return the text from the file test/com/moclojer/resources/text-plan.json
.
{% endswagger-description %}
{% swagger-response status="200: OK" description="" %}
{
"a": 123,
"b": "abc"
}
{% endswagger-response %} {% endswagger %}
You can use the json
provider to make URL (site) requests and have it returned to the endpoint:
- endpoint:
method: GET
path: /pokemon/phanpy
response:
status: 200
headers:
Content-Type: application/json
external-body:
provider: json
path: https://pokeapi.co/api/v2/pokemon/phanpy
Swagger:
{% swagger method="get" path="/pokemon/phanpy" baseUrl="" summary="" %}
{% swagger-description %}
Will return the text from the URL https://pokeapi.co/api/v2/pokemon/phanpy
.
{% endswagger-description %}
{% swagger-response status="200: OK" description="" %}
{"abilities":
[{"ability":
{
"name":"pickup",
"url":"https://pokeapi.co/api/v2/ability/53/"
}
...
{% endswagger-response %} {% endswagger %}
xlsx
Excel typeThis is where the use of moclojer starts to get different, as it is possible to “transform” an Excel spreadsheet into an API return (json
).
- endpoint:
method: GET
path: /xlsx
response:
status: 200
headers:
Content-Type: application/json
external-body:
provider: xlsx
path: excel-sample.xlsx
sheet-name: test
Excel spreadsheet example (excel-sample.xlsx
):
name | langs -- | -- avelino | clojure, go chicao | clojure, python
Swagger:
{% swagger method="get" path="/xlsx" baseUrl="" summary="" %}
{% swagger-description %}
Will return the text from the file test/com/moclojer/resources/excel-sample.xlsx
.
{% endswagger-description %}
{% swagger-response status="200: OK" description="" %}
[
{"name": "avelino", "langs": "clojure, go"},
{"name": "chicao","langs": "clojure, python"}
]
{% endswagger-response %} {% endswagger %}
Can you improve this documentation?Edit on GitHub
cljdoc is a website building & hosting documentation for Clojure/Script libraries
× close