Post by bil on Apr 21, 2017 7:11:33 GMT
Hello all,
I am currently designing a Redfish-based API and having problems finding a suitable toolset – especially for the documentation of the API.
Is there a recommended tool to document the HTTP endpoints, which are available through the API?
I have tried various standard tools to achieve this but got stuck with each of them.
The Swagger editor allows for external JSON schema files, but throws the error "Maximum call stack size exceeded" with the following snippet. I assume, that the parser has problems to follow the nesting structure of the Redfish schema.
:
I had the same experience describing the API in RAML with Mulesoft’s API workbench or the online API designer. The following leads to the error "JSON schema contains circular references", which is shown, when the internal error "Maximum call stack size exceeded" was thrown.
I know, that these tools are out of Redfish's scope but my resulting question is: Is there a tool which I can use to describe the usage of my API or do I have to describe it manually?
The "doc-generator", included in the Redfish-Tools, only generates a documentation of the schema files without the endpoints.
Any suggestions are appreciated!.
Thanks in advance!
I am currently designing a Redfish-based API and having problems finding a suitable toolset – especially for the documentation of the API.
Is there a recommended tool to document the HTTP endpoints, which are available through the API?
I have tried various standard tools to achieve this but got stuck with each of them.
The Swagger editor allows for external JSON schema files, but throws the error "Maximum call stack size exceeded" with the following snippet. I assume, that the parser has problems to follow the nesting structure of the Redfish schema.
:
swagger: "2.0"
info:
version: "0.1.0"
title: My API
basePath: /redfish/v1
schemes:
- https
consumes:
- application/json
produces:
- application/json
tags:
- name: "/redfish/v1"
description: DMTF/SPMF Redfish v1.1.0
paths:
/:
get:
summary: retrieve service root resource
description: This object represents the root Redfish service.
operationId: getServiceRoot
tags: [ "/redfish/v1" ]
responses:
200:
description: Success
schema:
$ref: http://redfish.dmtf.org/schemas/v1/ServiceRoot.v1_1_1.json#/definitions/ServiceRoot
I had the same experience describing the API in RAML with Mulesoft’s API workbench or the online API designer. The following leads to the error "JSON schema contains circular references", which is shown, when the internal error "Maximum call stack size exceeded" was thrown.
#%RAML 1.0
title: My API
version: 0.1.0
baseUri: /redfish/v1
types:
ServiceRoot: !include http://redfish.dmtf.org/schemas/v1/ServiceRoot.v1_1_1.json#/definitions/ServiceRoot
/:
get:
responses:
200:
body:
application/json:
type: ServiceRoot
I know, that these tools are out of Redfish's scope but my resulting question is: Is there a tool which I can use to describe the usage of my API or do I have to describe it manually?
The "doc-generator", included in the Redfish-Tools, only generates a documentation of the schema files without the endpoints.
Any suggestions are appreciated!.
Thanks in advance!