Bootprint-module to render OpenAPI specifications, this repository has moved to https://github.com/bootprint/bootprint-monorepo/tree/master/packages/bootprint-openapi
License: MIT License
Is YAML supported by this project? If so I am having issues getting my model definitions to be included in the generated html page.
I just saw #15 which was moved to an issue in bootprint core. Should I be addressing my issue there instead?
Is there any way to link to a relative URL?
1st problem: After installing bootprint and bootprint swagger when I start bootprint I get a message complaining about missing "handelbars". There might be a missing dependency to handlebars. After installing handlebars I these versions:
├─┬ [email protected]
│ └─┬ [email protected]
│ └── [email protected]
├── [email protected]
├─┬ [email protected]
│ └── [email protected]
└── [email protected]
After calling
bootprint swagger http://localhost:53108/backend/swagger/docs/v1 neu
I get:
Loading bootprint-swagger 0.11.0
Loading bootprint-json-schema 0.8.1
Loading bootprint-base 0.6.1
[object Object]
No output is generated at all.
In the requests where payload is JSON object then the type (or schema) is not captured in the document. Instead the data type is shown as 'object'.
The code (below) between triple backquotes is not output in the bootprint HTML file:
swagger: "2.0"
info:
title: XXX
description: XXX
version: "0.1"
host:
api.xxx.org
schemes:
- https
produces:
- application/json
paths:
/foo/bar:
get:
summary: Foo bar
description: |
Lorem ipsum dolor sit amet
```{
id : "xxx",
xxx:["xxx"
name : {
en:" xxxx",
fr:""
}
```
responses:
200:
description: |
Lorem ipsum
schema:
type: integer
E.g., in the following, the description emerges as plain text, despite having GitHub-flavored Markdown inside.
{
"swagger": "2.0",
"info": {
"title": "SmartGift API",
"description": "This is the API to manage blah. The API is more extensive than is presented here, but in the interests of simplification, we are only presenting part of it. You typically will need to call on only **3 endpoints**: ```GET /emails```, ```POST /products```, and ```POST /cereal```. To see just the most-relevant endpoints, filter by the \"Frequently Used\" tag.",
"version": "1.0.0",
"contact": {
"name": "API Support",
"url": "http://developers.smartgiftit.com",
"email": "[email protected]"
}
},The Parameter Definitions Object should is currently ignored and should be included into the templates.
When defining a REST API it is convenient to be able to define a list of "global" responses that can be referenced from multiple REST methods. However, when using this feature, the HTML document rendered by Bootprint Swagger looks wrong.
See this example:
{
"swagger" : "2.0",
"info" : {
"description" : "TODO",
"version" : "0.0.1",
"title" : "API Spec",
"termsOfService" : "TODO"
},
"basePath" : "/v1",
"schemes" : [ "http" ],
"paths" : {
"/aaa" : {
"post" : {
"tags" : [ "AAA" ],
"summary" : "TODO",
"description" : "TODO",
"operationId" : "aaa",
"consumes" : [ "application/json" ],
"produces" : [ "application/json" ],
"parameters" : [ {
"in" : "body",
"name" : "body",
"description" : "TODO",
"required" : true,
"schema" : {
"$ref" : "#/definitions/AAA"
}
} ],
"responses" : {
"200" : {
"description" : "Success"
},
"401" : {
"$ref" : "#/responses/401"
},
"405" : {
"description" : "Invalid data"
}
}
}
}
},
"definitions" : {
"AAA" : {
"allOf" : [ {
"$ref" : "#/definitions/BBB"
}, {
"type" : "object",
"properties" : {
"propA" : {
"type" : "string"
},
"propB" : {
"type" : "string"
}
}
} ]
},
"BBB" : {
"type" : "object",
"properties" : {
"propA" : {
"type" : "string"
}
}
},
"UnauthorizedResponse" : {
"type" : "object",
"properties" : {
"code" : {
"type" : "integer",
"description" : "Error code."
},
"test" : {
"type" : "string",
"description" : "Error message."
}
}
}
}In the rendered documentation for the /aaa REST method there should be a reference to the definition of the UnauthorizedResponse object. But instead there is a "dead" reference to #/responses/401.
I would like the parameters which are referenced using a $ref tag o be displayed in a similar way as the parameters which are defined inline are displayed.
I have parameters referenced using $ref tags as shown in the image below:
I would like these parameters to be displayed like the inline parameters as shown below:
This is actually an issue for bootprint-json-schema.
The "pattern" property should be display in the datatype-partial of the bootprint-schema project.
Testcases are currently written in this project and there should be one for this issue as well (sometime this might be consolidated, but currently, test cases are only set up here and no other project is using bootprint-json-schema.
When I run bootprint swagger http://petstore.swagger.io/v2/swagger.json doc, I get the following output:
Loading bootprint-swagger 0.13.1
Loading bootprint-json-schema 0.8.4
Loading bootprint-base 0.6.3
But nothing happens after that. No files were put in the doc directory.
The Default request content-types and Default response content-types both list
the consumes field of the swagger object.
The corresponding handlebar body.hbs needs to be changed to:
<div id="sw-default-consumes" class="sw-default-value">
<span class="sw-default-value-header">Default request content-types:</span>
{{#each consumes}}{{.}}{{#unless @last}}, {{/unless}}{{/each}}
</div>
<div id="sw-default-produces" class="sw-default-value">
<span class="sw-default-value-header">Default response content-types:</span>
{{#each produces}}{{.}}{{#unless @last}}, {{/unless}}{{/each}}
</div>
Also both are always created even if no consumes or produces is given in the swagger
object.
The JSON input should be validated against the swagger JSON-schema in the lib/preprocessor.js to avoid misleading exceptions in the preprocessor (see #9)
It will be nice if all the css code is put in html file so that only 1 file gets generated. It's easier to share one html file than the need of having two separate files to view the generated spec.
Been trying to figure out what the problem is here, but can't seem to. Command I'm running is:
bootprint swagger http://localhost:3000/orca.json html
also tried just referencing the file locally, like:
bootprint swagger orca.json html
it always errors with:
/usr/local/lib/node_modules/bootprint/node_modules/q/q.js:155
throw e;
^
TypeError: undefined is not a function
at /usr/local/lib/node_modules/bootprint-swagger/lib/preprocessor.js:15:61
at Array.forEach (native)
at /usr/local/lib/node_modules/bootprint-swagger/lib/preprocessor.js:13:24
at Array.forEach (native)
at Object.module.exports (/usr/local/lib/node_modules/bootprint-swagger/lib/preprocessor.js:12:26)
at /usr/local/lib/node_modules/bootprint/lib/bootprint.js:64:32
at _fulfilled (/usr/local/lib/node_modules/bootprint/node_modules/q/q.js:834:54)
at self.promiseDispatch.done (/usr/local/lib/node_modules/bootprint/node_modules/q/q.js:863:30)
at Promise.promise.promiseDispatch (/usr/local/lib/node_modules/bootprint/node_modules/q/q.js:796:13)
at /usr/local/lib/node_modules/bootprint/node_modules/q/q.js:604:44
My JSON file is:
{
"swagger": "2.0",
"info": {
"version": "1.0",
"title": "Orca API",
"description": "This API allows you to programmatically retrieve composed options strategies based on your forecast and market data.\n\nThis API Uses OAuth2 to control access. All methods except the /auth methods expect a valid \"Authorization: Bearer XXXX\" header to be passed with the request.\n"
},
"host": "orca.trade",
"basePath": "/Code/prod/api/public/1_0",
"consumes": [
"application/json"
],
"produces": [
"application/json"
],
"parameters": {
"accessToken": {
"name": "Access Token",
"in": "header",
"required": true,
"type": "string",
"description": "OAuth 2 Access token. Send in the Authorization header as Bearer XXXXXXXX."
},
"symbol": {
"name": "symbol",
"in": "formData",
"required": true,
"schema": {
"$ref": "symbol"
},
"description": "The underlying symbol information."
},
"request": {
"name": "request",
"in": "formData",
"required": true,
"schema": {
"$ref": "request"
},
"description": "The forecast and other information needed when requesting strategies."
},
"optionChain": {
"name": "optionChain",
"in": "formData",
"required": true,
"schema": {
"$ref": "optionChain"
},
"description": "The quoted option chain provided when requesting strategies."
}
},
"paths": {
"/auth/login": {
"get": {
"summary": "Redirects to login page for OAuth2 login",
"description": "Redirects to https://www.orca.trade/oauth/login"
}
},
"/auth/getLoginUrl": {
"get": {
"summary": "Returns OAuth2 Login URL",
"description": "Returns \"url\":\"https://www.orca.trade/oauth/login\""
}
},
"/auth/getToken": {
"post": {
"summary": "Exchange an Auth Code for an Access Token",
"parameters": {
"authCode": "The authorization code returned from the OAuth2 signin process"
},
"responses": {
"200": {
"description": "Returns the token in the body of the request as JSON. \"token\":\"12345678990\""
}
}
}
},
"/market/preloadOptionChain/{symbol}": {
"get": {
"summary": "Preload an option chain on the server (server contacts your UI).",
"description": "Informs the server what symbol you're using and asks it to retrieve a static option chain from your the API. This makes the subsequent retrieval of strategies significantly faster. \n\nThe endpoint from which the market data is retrieved is determined by the account information attached to the user's access token, and is set up by calling Orca customer support.\n",
"parameters": [
{
"name": "symbol",
"in": "path",
"required": true,
"description": "The underlying symbol code. (E.g. \"AAPL\")",
"type": "string"
}
]
},
"post": {
"summary": "Preload an option chain on the server (you supply the option chain as JSON data).",
"description": "Send a quoted option chain to the server, for the server to use on subsequent strategy requests. Chain will be cached for two (2) minutes and used by any other users from your organization. This makes the subsequent retrieval of strategies significantly faster. \n\nThe endpoint from which the market data is retrieved is determined by the account information attached to the user's access token, and is set up by calling Orca customer support.\n",
"responses": {
"200": {
"description": "true (option chain loaded successfully)"
},
"401": {
"description": "no stream endpoint set for this user's account."
},
"403": {
"description": "Invalid auth key"
},
"500": {
"description": "Other Error. Specified with status:\"failed\", error: \"error text here\"\n",
"schema": {
"type": "object",
"$ref": "error"
}
}
}
}
},
"/market/stream/{symbol}": {
"get": {
"summary": "Tell the server to start streaming data about the given symbol.",
"description": "Informs the server what symbol you're using, and tells it to start streaming data from your API. This makes the subsequent retrieval of strategies significantly faster. \n\nUse this instead of preloadOptionChain if you have a fast-moving symbol, or have many users who may request this symbol (e.g. a popular one, like AAPL).\n\nThe endpoint from which the market data is retrieved is determined by the account information attached to the user's access token, and is set up by calling Orca customer support.\n",
"parameters": [
{
"name": "symbol",
"in": "path",
"required": true,
"description": "The underlying symbol code. (E.g. \"AAPL\")",
"type": "string"
}
],
"responses": {
"200": {
"description": "true (successful stream start)"
},
"401": {
"description": "no stream endpoint set for this user's account."
},
"403": {
"description": "Invalid auth key"
},
"500": {
"description": "Other Error. Specified with status:\"failed\", error: \"error text here\"\n",
"schema": {
"type": "object",
"$ref": "error"
}
}
}
}
},
"/core/strategies/{symbol}/{amount}/{price}/{date}/{useIv}/{iv}/{uprice}/{username}/{oaLevel}/{accountType}": {
"get": {
"summary": "Returns composed strategies for the given forecast.",
"description": "Only use this if you have previously called *preloadOptionChain* or *stream*. Otherwise use the POST method to pass everything at once.",
"parameters": [
{
"name": "symbol",
"in": "path",
"required": true,
"description": "The underlying symbol code. (E.g. \"AAPL\")",
"type": "string"
},
{
"name": "amount",
"in": "path",
"required": true,
"description": "The amount you are willing to commit to the trade.",
"type": "float",
"format": "two-digit precision"
},
{
"name": "price",
"in": "path",
"required": true,
"description": "The forecast price (what price you believe the stock will be on the forecast data)",
"type": "float",
"format": "two-digit precision"
},
{
"name": "date",
"in": "path",
"required": true,
"description": "The forecast date (at which date you believe the stock will reach the forecast price).",
"type": "date",
"format": "YYYY-MM-DD"
},
{
"name": "useIv",
"in": "path",
"required": true,
"description": "Pass true or false. Tells the server whether to pay attention to the next parameter (iv).",
"type": "boolean"
},
{
"name": "iv",
"in": "path",
"requred": true,
"description": "The forecasted implied volatility. If you passed useIv=false then this value is ignored, but passing 0 is conventional.",
"type": "float",
"format": "two-digit precision"
},
{
"name": "uprice",
"in": "path",
"required": true,
"description": "The current price of the underlying.",
"type": "float",
"format": "two-digit precision"
},
{
"name": "username",
"in": "path",
"required": true,
"description": "The Orca username of the current user. !!$$$ This needs to go away, we can get the user from their auth token!!$$$.",
"type": "string"
},
{
"name": "oaLevel",
"in": "path",
"required": true,
"description": "The Option Approval level of the current user on a 1-5 scale.\n1: Covered calls\n2: XXX\n3: XXX\n4: XXX\n5: All option strategies\n",
"type": "integer",
"enum": [
1,
2,
3,
4,
5
]
},
{
"name": "accountType",
"in": "path",
"required": true,
"description": "Type of account you will use to trade these strategies (margin or cash).",
"type": "string"
}
],
"responses": {
"200": {
"description": "Array of composed strategies",
"schema": {
"type": "array",
"items": {
"$ref": "strategy"
}
}
},
"403": {
"description": "Invalid auth key"
},
"500": {
"description": "Other Error. Specified with status:\"failed\", error: \"error text here\"\n",
"schema": {
"type": "object",
"$ref": "error"
}
}
}
}
},
"/core/strategies": {
"post": {
"summary": "Returns strategies for the given request(forecast), symbol, and option chain.",
"description": null,
"parameters": [
{
"name": "request",
"in": "formData",
"required": true,
"schema": {
"$ref": "request"
},
"description": "The forecast and other information needed when requesting strategies."
},
{
"name": "symbol",
"in": "formData",
"required": true,
"schema": {
"$ref": "symbol"
},
"description": "The underlying symbol information."
},
{
"name": "optionChain",
"in": "formData",
"required": true,
"schema": {
"$ref": "optionChain"
},
"description": "The quoted option chain provided when requesting strategies."
}
],
"responses": {
"200": {
"description": "The composed strategies",
"schema": {
"type": "array",
"items": {
"$ref": "strategy"
}
}
},
"403": {
"description": "Invalid auth key"
},
"500": {
"description": "Other Error. Specified with status:\"failed\", error: \"error text here\"\n",
"schema": {
"type": "object",
"$ref": "error"
}
}
}
}
}
},
"definitions": {
"error": {
"description": "an error object",
"required": [
"status",
"error"
],
"properties": {
"status": {
"type": "string",
"minLength": 1,
"maxLength": 20,
"pattern": "^failed|success",
"description": "failed/success flag"
},
"error": {
"type": "string",
"minLength": 0,
"description": "A detailed description of the error."
}
},
"example": {
"status": "failed",
"error": "No streaming endpoint for brokerage."
}
},
"option": {
"description": "an option",
"required": [
"ask",
"bid",
"strike",
"daysToExpiry",
"quantity",
"opcode",
"call_or_put",
"volume",
"opeinInterest",
"itheta",
"symbol",
"id"
],
"properties": {
"ask": {
"type": "number",
"description": "latest ask price in decimal format (two-digit precision)"
},
"bid": {
"type": "number",
"description": "latest bid price in decimal format (two-digit precision)"
},
"price": {
"type": "number",
"description": "latest average price in decimal format (two-digit precision)"
},
"strike": {
"type": "number",
"description": "strike price price in decimal format (two-digit precision)"
},
"daysToExpiry": {
"type": "integer",
"description": "Whole or partial days left until the expiry of the option. If today is the expiry date then daysToExpiry = 1."
},
"quantity": {
"type": "integer",
"description": "Number of units of this option to buy or sell to create one strategy. Negative numbers indicate selling the option, positive numbers buying. \n\nExample - In a bull call vertical spread, the lower strike would have a positive 1 quantity, and the higher a -1 quantity.\n"
},
"opcode": {
"type": "string",
"description": "The option symbol in OCC format. (E.g.: LAMR150117C00052500)\n"
},
"call_or_put": {
"type": "string",
"description": "C for call, P for put, U for an underlying leg (present in covered calls and collars)\n"
},
"volume": {
"type": "integer",
"description": "daily trade volume"
},
"openInterest": {
"type": "integer",
"description": "the total number of option contracts that are currently open for this option - in other words, contracts that have been traded but not yet liquidated by either an offsetting trade or an exercise or assignment\n"
},
"itheta": {
"type": "number",
"description": "the rate of decline in the value of an option due to the passage of time) for the option."
},
"symbol": {
"type": "string",
"description": "The underlying symbol for this option. E.g. \"AAPL\"."
},
"id": {
"description": "same as opcode"
}
}
},
"optionChain": {
"description": "an option chain for a single underlying",
"required": [
"optionChain"
],
"properties": {
"optionChain": {
"description": "An array of option objects representing all tradeable options for a given underlying symbol.",
"type": "array",
"items": [
{
"$ref": "option"
}
]
}
}
},
"symbol": {
"description": "represents an underlying symbol used in a POST /strategies request",
"required": [
"ask",
"bid",
"last",
"symbol"
],
"properties": {
"ask": {
"description": "latest ask price for the underlying in decimal format (two-digit precision)",
"type": "number"
},
"bid": {
"description": "latest bid price for the underlying in decimal format (two-digit precision)",
"type": "number"
},
"last": {
"description": "latest average price for the underlying in decimal format (two-digit precision)",
"type": "number"
},
"symbol": {
"description": "the underlying symbol code (e.g. \"AAPL\" or \"GM\")",
"type": "string"
}
}
},
"strategiesRequest": {
"description": "forecast and related data used to request strategies",
"required": [
"price",
"date",
"useIv",
"iv"
],
"properties": {
"ask": {
"description": "the latest ask price for the underlying",
"type": "number"
},
"bid": {
"description": "the latest bid price for the underlying",
"type": "number"
},
"last": {
"description": "the latest average price for the underlying",
"type": "number"
},
"symbol": {
"description": "the underlying symbol code (e.g. \"AAPL\" or \"GM\")",
"type": "string"
}
}
},
"strategy": {
"description": "an individual strategy result",
"properties": {
"strategy": {
"description": "The name of the strategy, in Orca nomenclature.\n"
},
"composition": {
"description": "The makeup of the strategy. See JSON for more detail.",
"type": "array",
"items": [
{
"properties": null,
"strategy": {
"type": "string",
"description": "The name of the strategy, in Orca nomenclature.\n"
},
"profitTarget": {
"type": "number",
"description": "The expected profit for this strategy if the underlying hits the forecast price on the forecast day"
},
"amount": {
"type": "number",
"description": "The estimated total cost of the strategy, including commissions. Usually negative.\n"
},
"comissionTotal": {
"type": "number",
"description": "The estimated total commissions. Ususally negative."
},
"strategyQuantity": {
"type": "string",
"description": "The number of strategies possible to put on for \"amount\"."
},
"uPrice": {
"type": "number",
"description": "The underlying price used in to create this strategy."
},
"iv": {
"type": "number",
"description": "The underlying implied volatility used to create this strategy"
},
"fPrice": {
"type": "number",
"description": "The forecast price used to create this strategy"
},
"fDays": {
"type": "number",
"description": "The number of whole or partial days from today that the given forecast day represents. If it is 1pm on 1/1/2016 and the forecast date is 1/2/2016, fDays = 1. If it is 1pm on 1/1/2016 and the forecast date is 1/15/2016, fDays = 16.\n"
},
"fIV": {
"type": "number",
"description": "The implied volatility forecasted by the user, if any.\n"
},
"nodes": {
"description": "The array of the individual legs that make up this strategy.",
"items": [
{
"$ref": "option"
}
]
}
}
]
}
}
},
"strategiesResponse": {
"description": "An array of strategies returned from a strategiesRequest",
"properties": {
"results": {
"description": "An array of strategy objects.",
"type": "array",
"items": [
{
"$ref": "strategy"
}
]
}
}
},
"request": {
"description": "forecast and related data used to request strategies",
"required": [
"username",
"brokerage",
"accountType",
"optionApprovalLevel",
"forecast"
],
"properties": {
"username": {
"description": "the latest ask price for the underlying. Decimal with 2-digit precision.",
"type": "string"
},
"brokerage": {
"description": "the latest bid price for the underlying. Decimal with 2-digit precision.",
"type": "string"
},
"accountType": {
"description": "either \"cash\" or \"margin\"",
"type": "string"
},
"forecast": {
"$ref": "forecast"
}
},
"example": {
"request": {
"username": "adamjerickson",
"brokerage": "eSignal",
"accountType": "margin",
"optionApprovalLevel": 5,
"forecast": {
"price": 123.12,
"date": 20151225,
"amount": 12345.56,
"useIv": true,
"iv": 0.32
}
}
}
},
"forecast": {
"description": "A trader's market sentiment.",
"required": [
"price",
"date",
"amount",
"useIv"
],
"properties": {
"price": {
"type": "number",
"description": "the price the trader believes the stock will reach. This is a nominal value, not relative to the current price.\n"
},
"date": {
"type": "date",
"format": "YYYYMMDD",
"description": "the date upon which the trader believes the stock will reach the forecasted price."
},
"amount": {
"type": "number",
"description": "the amount the user is willing to commit to the trade. Used to calculate strategy quantity, and in some cases, filter out strategies that are too expensive.\n"
},
"useIv": {
"type": "boolean",
"description": "true|false. Whether to use the implied volatility given below."
},
"iv": {
"type": "number",
"description": "the forecasted implied volatility over the forecast period"
}
},
"example": {
"forecast": {
"price": 123.12,
"date": 20151225,
"amount": 12345.56,
"useIv": true,
"iv": 0.32
}
}
}
}
}
Tag descriptions are currently not treated as markdown and therefore not converted to HTML. But this should be the case
It would be nice to have bootprint output the swagger-ui-style Model Schema, which provides something of an example value as documentation (original discussion at #29 (comment))
Hello.
When I try to bootprint from a json file, I get:
marian@gimli ~/bootprint $ bootprint openapi ./calendar.json calendar
Loading bootprint-openapi 0.14.0
Loading bootprint-json-schema 0.8.4
Loading bootprint-base 0.6.3
/usr/lib/node_modules/bootprint/node_modules/q/q.js:155
throw e;
^
YAMLException: duplicated mapping key at line 1, column 33806:
... "The content","required":true}]},"delete":{"method":"DELETE","su ...
^
at generateError (/usr/lib/node_modules/bootprint/node_modules/js-yaml/lib/js-yaml/loader.js:161:10)
at throwError (/usr/lib/node_modules/bootprint/node_modules/js-yaml/lib/js-yaml/loader.js:167:9)
at storeMappingPair (/usr/lib/node_modules/bootprint/node_modules/js-yaml/lib/js-yaml/loader.js:304:7)
at readFlowCollection (/usr/lib/node_modules/bootprint/node_modules/js-yaml/lib/js-yaml/loader.js:719:7)
at composeNode (/usr/lib/node_modules/bootprint/node_modules/js-yaml/lib/js-yaml/loader.js:1328:11)
at readFlowCollection (/usr/lib/node_modules/bootprint/node_modules/js-yaml/lib/js-yaml/loader.js:714:7)
at composeNode (/usr/lib/node_modules/bootprint/node_modules/js-yaml/lib/js-yaml/loader.js:1328:11)
at readFlowCollection (/usr/lib/node_modules/bootprint/node_modules/js-yaml/lib/js-yaml/loader.js:714:7)
at composeNode (/usr/lib/node_modules/bootprint/node_modules/js-yaml/lib/js-yaml/loader.js:1328:11)
at readBlockMapping (/usr/lib/node_modules/bootprint/node_modules/js-yaml/lib/js-yaml/loader.js:1002:16)
Now, I don't see any duplicate entry. What's more, if I convert the json to yaml (for example, using http://jsontoyaml.com/), and then run bootprint the yaml file, it just works.
The enum keyword allows the list of valid values for a schema entry to be defined. It would be great if that was reflected on the documentation accordingly, by listing the different options automatically in the generated HTML.
Hi
I use the following in the swagger description
` |Field | Description|
|-----------|------------|
|defaultMessage|Human readable message explaining the reason why the field
value is erroneous.|
|field|The name of the JSON field that contains an erroneous value.|
|rejectedValue|The value that was submitted but rejected.|`
** Which produces the following the swagger editor screen **
However when I run bootprint openapi , final html page is not having table structure as above. Could you please advise ?
After bootprint openapi transformation
I have marked some parameters as required [e.g. in swagger.json - "required": true ] but in the generated documentation there is no indication that the parameter is required in the request. Red asterisk or a label indicating that the parameter is required would help.
(Extracted from #1)
"Examples" in the swagger-parts of the spec only seem to be possible within response definitions, which would go into the partials of this ("bootprint-swagger") module, namely swagger/responses.
A test case should be written to ensure this on each build
When I run:
$ bootprint swagger http://localhost:63342/blee2/documentation/api.json documentation/
I get:
{ [Error: Cannot find module './template/template.hbs'] code: 'MODULE_NOT_FOUND' }
It would be nice if the operationIds were included in the endpoint documentation.
I'm getting an error message, but it doesn't help me understand where in the document the problem is.
$ # bootprint swagger swagger.json /docs/target
Loading bootprint-swagger 0.9.2
Loading bootprint-json-schema 0.7.1
Loading bootprint-base 0.5.1
[TypeError: Cannot read property 'minimum' of undefined]
/usr/local/lib/node_modules/bootprint/node_modules/q/q.js:155
throw e;
^
TypeError: Cannot read property 'minimum' of undefined
at module.exports.json-schema--range (/usr/local/lib/node_modules/bootprint-swagger/node_modules/bootprint-json-schema/handlebars/helpers.js:52:27)
at wrapper (/usr/local/lib/node_modules/bootprint/node_modules/lodash/index.js:3533:19)
at Object.eval (eval at createFunctionContext (/usr/local/lib/node_modules/bootprint/node_modules/handlebars/dist/cjs/handlebars/compiler/javascript-compiler.js:221:23), <anonymous>:11:130)
at ret (/usr/local/lib/node_modules/bootprint/node_modules/handlebars/dist/cjs/handlebars/runtime.js:159:30)
at ret (/usr/local/lib/node_modules/bootprint/node_modules/handlebars/dist/cjs/handlebars/compiler/compiler.js:488:21)
at Object.invokePartial (/usr/local/lib/node_modules/bootprint/node_modules/handlebars/dist/cjs/handlebars/runtime.js:218:12)
at Object.invokePartialWrapper [as invokePartial] (/usr/local/lib/node_modules/bootprint/node_modules/handlebars/dist/cjs/handlebars/runtime.js:61:39)
at Object.eval (eval at createFunctionContext (/usr/local/lib/node_modules/bootprint/node_modules/handlebars/dist/cjs/handlebars/compiler/javascript-compiler.js:221:23), <anonymous>:14:23)
at ret (/usr/local/lib/node_modules/bootprint/node_modules/handlebars/dist/cjs/handlebars/runtime.js:159:30)
at ret (/usr/local/lib/node_modules/bootprint/node_modules/handlebars/dist/cjs/handlebars/compiler/compiler.js:488:21)A clean install of bootprint-swagger currently takes 136 MB. That is way too much. Check, whether there are unused dependencies and files that can be ignores in .npmignore
Is it possible to support yaml format for documentation?
It looks like now it is default format in Swagger Editor
Hi.
Do you have more handlebars templates for bootprint swagger (there is only 1 correct me if i'm wrong) ?
Is generating PDF possible ?
In the YAML file below, the first line is displayed but the second one is swallowed. Removing the newline makes the second line appear in the documentation.
swagger: "2.0"
info:
title: XXX
description: XXX
version: "0.1"
host:
api.xxx.org
schemes:
- https
produces:
- application/json
paths:
/foo/bar:
get:
summary: Foo bar
description: |
First line is displayed
Second line is swallowed
responses:
200:
description: |
Lorem ipsum
schema:
type: integer
I've started getting the above error when trying to generate swagger docs even from examples (such as petstore.yaml) from the swagger editor.
It seems during the merge config step the pre-processor is undefined, some abridged debug output plus the stack trace below. config.preprocessor is indeed undefined by the time customize-engine-handlebars/index.js gets it's hands on it.
customize:state New configuration +95ms { handlebars:
{ config:
{ partials: undefined,
helpers: undefined,
templates: undefined,
data: [Object],
preprocessor: undefined,
hbsOptions: undefined },
watched: [] },
less:
{ config: { main: [Object], paths: undefined },
watched:
[ '/usr/lib/node_modules/bootprint-openapi/less/theme.less',
'/usr/lib/node_modules/bootprint-openapi/less/variables.less' ] },
_metadata: { config: { modules: [Object] } } }
customize:base Building +2ms { handlebars:
{ partials: undefined,
helpers: undefined,
templates: undefined,
data:
{ swagger: '2.0',
info: [Object],
host: 'localhost:10010',
basePath: '/3',
schemes: [Object],
consumes: [Object],
produces: [Object],
securityDefinitions: [Object],
parameters: [Object],
paths: [Object],
definitions: [Object] },
preprocessor: undefined,
hbsOptions: undefined },
less:
{ main:
[ '/usr/lib/node_modules/bootprint-openapi/less/theme.less',
'/usr/lib/node_modules/bootprint-openapi/less/variables.less' ],
paths: undefined },
_metadata: { modules: [ [Object] ] } }
/usr/lib/node_modules/bootprint/node_modules/q/q.js:155
throw e;
^
TypeError: Property 'preprocessor' of object #<Object> is not a function
at Object.run (/usr/lib/node_modules/bootprint/node_modules/customize-engine-handlebars/index.js:132:21)
at /usr/lib/node_modules/bootprint/node_modules/customize-watch/node_modules/customize/index.js:291:25
at /usr/lib/node_modules/bootprint/node_modules/lodash/lodash.js:11671:23
at /usr/lib/node_modules/bootprint/node_modules/lodash/lodash.js:4143:15
at baseForOwn (/usr/lib/node_modules/bootprint/node_modules/lodash/lodash.js:2669:24)
at Function.mapValues (/usr/lib/node_modules/bootprint/node_modules/lodash/lodash.js:11670:7)
at /usr/lib/node_modules/bootprint/node_modules/customize-watch/node_modules/customize/index.js:288:22
at _fulfilled (/usr/lib/node_modules/bootprint/node_modules/q/q.js:834:54)
at self.promiseDispatch.done (/usr/lib/node_modules/bootprint/node_modules/q/q.js:863:30)
at Promise.promise.promiseDispatch (/usr/lib/node_modules/bootprint/node_modules/q/q.js:796:13)
This is on a fresh global install as per the instructions, Ubuntu 12.04.
Full debug output here: https://gist.github.com/robotrobot/e3909b0da6971d339b2f
Consider the following Swagger Spec snippet:
"definitions" : {
"AAA" : {
"allOf" : [ {
"$ref" : "#/definitions/BBB"
}, {
"type" : "object",
"properties" : {
"ttt" : {
"type" : "string"
}
}
} ]
},
"BBB" : {
"allOf" : [ {
"$ref" : "#/definitions/CCC"
}, {
"type" : "object",
"properties" : {
"vvv" : {
"type" : "string"
}
}
} ]
},
"CCC" : {
"type" : "object",
"properties" : {
"uuu" : {
"type" : "string"
},
"ppp" : {
"type" : "string"
}
}
}
}When you using "bootprint swagger" to generate HTML, then the object AAA only displays the property ttt (in addition, you can see that AAA inherits from BBB). So, in order to see all properties, you need to click on the BBB object and then on the CCC object (because BBB inherits from CCC).
It would be really cool if the generator had an option that would render all the inherited properties (directly in AAA), so that it becomes easier to see which properties are part of the definition of AAA.
I have created mock-up screenshots of how this could look:
Here the "INHERITED PROPERTIES" section is collapsed:
And here it is expanded:
Those are not displayed at the moment.
The following options are possible:
Which one is better?
The petstore-example still prints out an [Object object] or something like that. If someone has a good idea of how to format this tag, please tell me.
I'm having problems getting my custom partials to render. I'm using bootprint 0.7.3 with the swagger module. I have a config file (config.js) with the following content:
module.exports = {
"handlebars": {
"partials": "/full/path/to/partials"
}
}
The specified partials directory contains the following:
partials
└──swagger
└──paths.hbs
paths.hbs is a copy of the original partial with changes I addded.
I pass the config file as a parameter to bootprint:
bootprint -f config.js swagger swagger-schema/continuum-api.json out
Result:
HTML is built correctly but without the changes in my custom partials.
Expected:
HTML includes changes in custom partial.
Any idea what I'm missing?
Since openapi/swagger metadata can be used to generate both API documentation and API explorer, do you have any plans to create API explorer for the API interaction for a user ?
Swagger has a tool, named swagger-ui to do the same.
Does this support cross file references?
I have a yaml file with that looks like:
definitions:
Order:
$ref: order.yml
But it seems to just literally link to that file, rather than importing it into the spec.
Some very important fields seem to be missing from the Handlebars templates, such as host and basePath.
Unless this is "a feature not a bug", I will add them and submit a pull request.
Hi,
Path Item parameters should be treated as [Parameter Object | Reference Object](see https://github.com/swagger-api/swagger-spec/blob/master/versions/2.0.md#fixed-fields-4),
but it seems they are rendered as same as other Operation Objects like get, post, etc..
Thanks.
Hi, Is it possible to get SPA implemented while transforming from json to html which would have navigation bar on the left hand side ? Is any one working on that ?
bootprint-swagger does not yet group methods by their tag and display tag descritpion (like swagger-ui does). If anyone wants to implement this. I believe the following changes are needed:
lib/preprocessor.js must be changed to group methods by tag (see the documentation for details about the preprocessorpartials/base/body.hbs must call a new partial instead of {{> swagger/path}}Hi, I just performed a fresh install but it seems not to working at all. Here are the installation steps, actual versions and what I get after a try:
$ npm install -g bootprint
npm WARN engine [email protected]: wanted: {"node":">=0.12.2 <0.14"} (current: {"node":"5.2.0","npm":"3.3.12"})
npm WARN engine [email protected]: wanted: {"node":"^4.0"} (current: {"node":"5.2.0","npm":"3.3.12"})
npm WARN install Couldn't install optional dependency: Unsupported
> [email protected] preinstall C:\Users\MyUser\AppData\Roaming\npm\node_modules\.staging\typechecker-ba5d125d00896ed54ff74417145cc3f0
> node ./cyclic.js
C:\Users\MyUser\AppData\Roaming\npm\bootprint -> C:\Users\MyUser\AppData\Roaming\npm\node_modules\bootprint\bin\bootprint.js
C:\Users\MyUser\AppData\Roaming\npm
└─┬ [email protected]
├─┬ [email protected]
│ └── [email protected]
├─┬ [email protected]
│ └── [email protected]
├─┬ [email protected]
│ ├─┬ [email protected]
│ │ ├─┬ [email protected]
│ │ │ ├── [email protected]
│ │ │ └── [email protected]
│ │ ├─┬ [email protected]
│ │ │ └── [email protected]
│ │ └─┬ [email protected]
│ │ ├── [email protected]
│ │ └── [email protected]
│ ├── [email protected]
│ └─┬ [email protected]
│ └── [email protected]
├─┬ [email protected]
│ └─┬ [email protected]
│ ├─┬ [email protected]
│ │ └── [email protected]
│ ├── [email protected]
│ ├── [email protected]
│ ├── [email protected]
│ ├─┬ [email protected]
│ │ └── [email protected]
│ ├─┬ [email protected]
│ │ └── [email protected]
│ ├─┬ [email protected]
│ │ ├── [email protected]
│ │ ├── [email protected]
│ │ ├── [email protected]
│ │ ├─┬ [email protected]
│ │ │ └── [email protected]
│ │ ├── [email protected]
│ │ ├── [email protected]
│ │ ├─┬ [email protected]
│ │ │ └── [email protected]
│ │ ├─┬ [email protected]
│ │ │ ├─┬ [email protected]
│ │ │ │ ├── [email protected]
│ │ │ │ ├── [email protected]
│ │ │ │ ├─┬ [email protected]
│ │ │ │ │ └── [email protected]
│ │ │ │ ├── [email protected]
│ │ │ │ └── [email protected]
│ │ │ ├─┬ [email protected]
│ │ │ │ ├── [email protected]
│ │ │ │ ├─┬ [email protected]
│ │ │ │ │ └── [email protected]
│ │ │ │ ├── [email protected]
│ │ │ │ └── [email protected]
│ │ │ └─┬ [email protected]
│ │ │ └── [email protected]
│ │ ├─┬ [email protected]
│ │ │ ├── [email protected]
│ │ │ ├── [email protected]
│ │ │ ├── [email protected]
│ │ │ └── [email protected]
│ │ ├─┬ [email protected]
│ │ │ ├── [email protected]
│ │ │ ├─┬ [email protected]
│ │ │ │ ├── [email protected]
│ │ │ │ ├── [email protected]
│ │ │ │ └── [email protected]
│ │ │ └─┬ [email protected]
│ │ │ ├── [email protected]
│ │ │ ├── [email protected]
│ │ │ ├── [email protected]
│ │ │ ├── [email protected]
│ │ │ ├── [email protected]
│ │ │ ├── [email protected]
│ │ │ └── [email protected]
│ │ ├── [email protected]
│ │ ├── [email protected]
│ │ ├── [email protected]
│ │ ├─┬ [email protected]
│ │ │ └── [email protected]
│ │ ├── [email protected]
│ │ ├── [email protected]
│ │ ├── [email protected]
│ │ ├── [email protected]
│ │ ├── [email protected]
│ │ └── [email protected]
│ └── [email protected]
├─┬ [email protected]
│ ├─┬ [email protected]
│ │ ├─┬ [email protected]
│ │ │ ├── [email protected]
│ │ │ └─┬ [email protected]
│ │ │ ├─┬ [email protected]
│ │ │ │ └── [email protected]
│ │ │ ├── [email protected]
│ │ │ ├─┬ [email protected]
│ │ │ │ ├─┬ [email protected]
│ │ │ │ │ └─┬ [email protected]
│ │ │ │ │ ├── [email protected]
│ │ │ │ │ ├── [email protected]
│ │ │ │ │ ├── [email protected]
│ │ │ │ │ └── [email protected]
│ │ │ │ ├── [email protected]
│ │ │ │ └── [email protected]
│ │ │ ├── [email protected]
│ │ │ ├─┬ [email protected]
│ │ │ │ ├─┬ [email protected]
│ │ │ │ │ └── [email protected]
│ │ │ │ └── [email protected]
│ │ │ ├── [email protected]
│ │ │ ├─┬ [email protected]
│ │ │ │ └── [email protected]
│ │ │ ├── [email protected]
│ │ │ ├─┬ [email protected]
│ │ │ │ ├─┬ [email protected]
│ │ │ │ │ └── [email protected]
│ │ │ │ └── [email protected]
│ │ │ ├─┬ [email protected]
│ │ │ │ ├── [email protected]
│ │ │ │ └── [email protected]
│ │ │ └─┬ [email protected]
│ │ │ ├── [email protected]
│ │ │ └── [email protected]
│ │ ├── [email protected]
│ │ ├── [email protected]
│ │ ├── [email protected]
│ │ ├─┬ [email protected]
│ │ │ └── [email protected]
│ │ ├─┬ [email protected]
│ │ │ └── [email protected]
│ │ ├── [email protected]
│ │ └─┬ [email protected]
│ │ ├── [email protected]
│ │ ├── [email protected]
│ │ └─┬ [email protected]
│ │ ├── [email protected]
│ │ ├── [email protected]
│ │ ├── [email protected]
│ │ ├── [email protected]
│ │ └── [email protected]
│ ├─┬ [email protected]
│ │ ├── [email protected]
│ │ ├─┬ [email protected]
│ │ │ ├── [email protected]
│ │ │ └─┬ [email protected]
│ │ │ ├── [email protected]
│ │ │ └─┬ [email protected]
│ │ │ ├─┬ [email protected]
│ │ │ │ ├─┬ [email protected]
│ │ │ │ │ ├─┬ [email protected]
│ │ │ │ │ │ └── [email protected]
│ │ │ │ │ ├─┬ [email protected]
│ │ │ │ │ │ ├─┬ [email protected]
│ │ │ │ │ │ │ ├─┬ [email protected]
│ │ │ │ │ │ │ │ ├── [email protected]
│ │ │ │ │ │ │ │ └── [email protected]
│ │ │ │ │ │ │ └── [email protected]
│ │ │ │ │ │ └── [email protected]
│ │ │ │ │ ├── [email protected]
│ │ │ │ │ └── [email protected]
│ │ │ │ └── [email protected]
│ │ │ └── [email protected]
│ │ └─┬ [email protected]
│ │ └─┬ [email protected]
│ │ ├── [email protected]
│ │ └── [email protected]
│ └─┬ [email protected]
│ ├─┬ [email protected]
│ │ └── [email protected]
│ ├── [email protected]
│ ├── [email protected]
│ └── [email protected]
├── [email protected]
├─┬ [email protected]
│ └── [email protected]
├── [email protected]
├─┬ [email protected]
│ ├─┬ [email protected]
│ │ └── [email protected]
│ └── [email protected]
├─┬ [email protected]
│ ├── [email protected]
│ ├─┬ [email protected]
│ │ ├── [email protected]
│ │ ├─┬ [email protected]
│ │ │ ├── [email protected]
│ │ │ ├── [email protected]
│ │ │ └─┬ [email protected]
│ │ │ ├── [email protected]
│ │ │ └── [email protected]
│ │ ├── [email protected]
│ │ ├─┬ [email protected]
│ │ │ ├─┬ [email protected]
│ │ │ │ └── [email protected]
│ │ │ ├── [email protected]
│ │ │ └── [email protected]
│ │ ├── [email protected]
│ │ ├── [email protected]
│ │ ├── [email protected]
│ │ ├── [email protected]
│ │ ├── [email protected]
│ │ ├─┬ [email protected]
│ │ │ └─┬ [email protected]
│ │ │ ├── [email protected]
│ │ │ ├── [email protected]
│ │ │ └── [email protected]
│ │ ├── [email protected]
│ │ ├── [email protected]
│ │ ├─┬ [email protected]
│ │ │ ├── [email protected]
│ │ │ └── [email protected]
│ │ ├─┬ [email protected]
│ │ │ └── [email protected]
│ │ ├── [email protected]
│ │ ├── [email protected]
│ │ ├─┬ [email protected]
│ │ │ └── [email protected]
│ │ ├─┬ [email protected]
│ │ │ └── [email protected]
│ │ ├─┬ [email protected]
│ │ │ ├── [email protected]
│ │ │ └─┬ [email protected]
│ │ │ └── [email protected]
│ │ ├── [email protected]
│ │ ├── [email protected]
│ │ ├── [email protected]
│ │ ├── [email protected]
│ │ ├── [email protected]
│ │ ├── [email protected]
│ │ ├─┬ [email protected]
│ │ │ └── [email protected]
│ │ ├── [email protected]
│ │ ├─┬ [email protected]
│ │ │ └── [email protected]
│ │ ├── [email protected]
│ │ └── [email protected]
│ ├─┬ [email protected]
│ │ ├── [email protected]
│ │ ├── [email protected]
│ │ ├── [email protected]
│ │ ├── [email protected]
│ │ ├── [email protected]
│ │ ├── [email protected]
│ │ └── [email protected]
│ ├─┬ [email protected]
│ │ └─┬ [email protected]
│ │ └── [email protected]
│ ├── [email protected]
│ ├─┬ [email protected]
│ │ └── [email protected]
│ ├─┬ [email protected]
│ │ ├── [email protected]
│ │ ├── [email protected]
│ │ ├── [email protected]
│ │ ├─┬ [email protected]
│ │ │ └── [email protected]
│ │ ├── [email protected]
│ │ └── [email protected]
│ └─┬ [email protected]
│ └─┬ [email protected]
│ ├── [email protected]
│ ├── [email protected]
│ ├── [email protected]
│ ├── [email protected]
│ ├── [email protected]
│ ├── [email protected]
│ ├── [email protected]
│ └── [email protected]
├── [email protected]
├── [email protected]
└── [email protected]
$ npm install -g bootprint-swagger
C:\Users\MyUser\AppData\Roaming\npm
└─┬ [email protected]
├─┬ [email protected]
│ └─┬ [email protected]
│ ├── [email protected]
│ ├─┬ [email protected]
│ │ ├─┬ [email protected]
│ │ │ ├── [email protected]
│ │ │ ├── [email protected]
│ │ │ ├── [email protected]
│ │ │ └── [email protected]
│ │ ├─┬ [email protected]
│ │ │ └── [email protected]
│ │ ├── [email protected]
│ │ └─┬ [email protected]
│ │ ├── [email protected]
│ │ ├── [email protected]
│ │ ├── [email protected]
│ │ ├── [email protected]
│ │ └─┬ [email protected]
│ │ ├── [email protected]
│ │ ├── [email protected]
│ │ ├── [email protected]
│ │ └── [email protected]
│ ├─┬ [email protected]
│ │ ├─┬ [email protected]
│ │ │ ├── [email protected]
│ │ │ └── [email protected]
│ │ ├─┬ [email protected]
│ │ │ └── [email protected]
│ │ └─┬ [email protected]
│ │ ├── [email protected]
│ │ └── [email protected]
│ ├── [email protected]
│ ├─┬ [email protected]
│ │ └── [email protected]
│ └── [email protected]
└── [email protected]
$ bootprint --version
0.8.3
$ npm ls -g | grep customize
│ ├─┬ [email protected]
│ ├─┬ [email protected]
│ ├─┬ [email protected]
│ │ ├─┬ [email protected]
│ ├── [email protected]
$ ls
swagger.json
$ bootprint swagger http://petstore.swagger.io/v2/swagger.json target
Loading bootprint-swagger 0.13.1
Loading bootprint-json-schema 0.8.4
Loading bootprint-base 0.6.3
$ ls
swagger.json
Let me know if is there any more info I can provide.
I have entries with parameters where in equals body, but none of them are being displayed in the HTML output.
Here's an excerpt of the JSON:
"paths": {
"/thingy": {
"post": {
"summary": "Create new thingys.",
"tags": [
"Thingys",
"Back-End Only"
],
"description": "Adds new thingys to the database, assigning them IDs and setting their last modification date/time to now.\n",
"parameters": [
{
"name": "thingys",
"in": "body",
"schema": {
"type": "array",
"items": {
"$ref": "#/definitions/Thingy"
},
"minItems": 1
},
"description": "An array of thingys to add to the database.\n"
}
],
"responses": {
"200": {
"description": "The thingys successfully inserted, complete with IDs and last modification fields.\n",
"schema": {
"type": "array",
"items": {
"$ref": "#/definitions/Thingy"
},
"minItems": 1
}
},
"400": {
"$ref": "#/responses/bad_request"
},
"403": {
"$ref": "#/responses/unauthorized"
}
}
}
}
BTW, the definitions are being expanded using swagger-expand-refs prior to submission to bootprint-swagger since they were causing issues.
When I generate the HTML, the Request Parameters section is simply not displayed at all, it goes straight from Description to Response Body.
My Definition objects are mostly blank.
When I send my yaml file to a co-worker who is on an older version(0.6.2), it works fine for him. Another co-worker on the newer version has the same problem as me (0.6.5)
I tried uninstalling and reinstalling to bootprint (0.7.1)and bootprint-swagger to (0.6.2) but I still get the same error, so I suspect it is another dependency that is causing the problem?
Suggestions?
As asked in this Stackoverflow question :The preprocessor could be enhanced to incoorporate the lucybot/api-spec-converter to support more api-definition-formats (like Swagger 1.2)
Moving here from: nknapp/swagger-to-html#3
There is a strange bug causing a tiny mistake in the CSS, making it invalid:
.radio input[type="radio"],.radio-inline input[type="radio"],.checkbox input[type="checkbox"],.checkbox-inline input[type="checkbox"] {
position:absolute;
margin-left:-20px;
margin-top:4px \9
}It probably won't effect most people since browsers do their best not to blow up, but a parser I use is not happy about it at all. =P
ParseError: Unrecognised input. Possibly missing opening '{' in /home/selby/projects/tenable/front/tmp/tree_merger-tmp_dest_dir-m8uv0yEk.tmp/app/styles/docs.less on line 5, column 38385:
Just in case anyone else is running into a similar problem, I wrote two bash scripts as a quick fix until I or someone else can figure out what the actual problem is.
#!/bin/bash
# ./fixcss.sh
# Usage: ./fixcss.sh <file.css> <keep backup: 1 or 0>
# Lets fix some CSS
cat $1 | grep --quiet -i "\\\9" && {
echo "CSS invalid, attempting to fix"
rm $1.bak -f
echo "Creating backup..."
mv $1 $1.bak
echo "Replacing invalid string..."
cat $1.bak | sed -r s/\\\\9//g | tee $1 1> /dev/null
cat $1 | grep --quiet -i "\\\9" && {
echo "CSS still invalid, sorry =/"
echo "Replacing original file..."
rm $1 -f
mv $1.bak $1
} || echo "Good to go =)"
$2 || echo "Removing backup..." && rm $1.bak -f
} || echo "Not broken, don't worry about it"
#!/bin/bash
# ./gendocs.sh
# Usage: ./gendocs.sh <swagger.json> <target_dir>
# Gets directory script is running from
DIR=$( cd "$( dirname "${BASH_SOURCE[0]}" )" && pwd )
# Generate Docs
bootprint swagger $1 $2
# Fix invalid CSS
$DIR/fixcss.sh $2/main.css
I keep them in my projects' ./scripts directory and call them like ./scripts/gendocs.sh swagger.json ./docs/spec, but you could also come up with more specific names, drop the .sh, toss them in ~/bin and add export PATH=$PATH:~/bin to your ~/.bashrc so that you can use them globally.
Hope this helps someone! Happy coding. =)
-Selby
http://selby.io
I have tried to use the online "playground" (http://bootprint.knappmeier.de/) to generate HTML docs for the following Swagger specification:
{
"swagger" : "2.0",
"info" : {
"description" : "TODO",
"version" : "0.0.1",
"title" : "API Spec",
"termsOfService" : "TODO"
},
"basePath" : "/v1",
"schemes" : [ "http", "https" ],
"paths" : {
"/aaa" : {
"post" : {
"tags" : [ "AAA" ],
"summary" : "TODO",
"description" : "TODO",
"operationId" : "aaa",
"consumes" : [ "application/json", "application/xml" ],
"produces" : [ "application/json", "application/xml" ],
"parameters" : [ {
"in" : "body",
"name" : "body",
"description" : "TODO",
"required" : true,
"schema" : {
"$ref" : "#/definitions/AAA"
}
} ],
"responses" : {
"200" : {
"description" : "Authentication was successful"
},
"405" : {
"description" : "Invalid data"
}
}
}
}
},
"definitions" : {
"AAA" : {
"allOf" : [ {
"$ref" : "#/definitions/BBB"
}, {
"type" : "object",
"properties" : {
"ttt" : {
"type" : "string"
}
}
} ]
},
"BBB" : {
"allOf" : [ {
"$ref" : "#/definitions/CCC"
}, {
"type" : "object",
"properties" : {
"vvv" : {
"type" : "string"
}
}
} ]
},
"CCC" : {
"type" : "object",
"properties" : {
"uuu" : {
"type" : "string"
},
"ppp" : {
"type" : "string"
}
}
}
}
}I really like the generated API docs, but unfortunately the objects AAA and BBB appear to be empty although they both contain properties.
Clearly, it seems like the use of allOf is not properly handled by bootprint-swagger.
If I convert the JSON specification to YAML and paste it to the Swagger Editor (http://editor.swagger.io/) then the objects AAA and BBB are correctly displayed.
https://github.com/swagger-api/swagger-spec/blob/master/versions/2.0.md#response-object defines a headers field, that is not displayed yet
If a PUT or POST body parameter schema has a read-only field, it should either be omitted from the parameter documentation of clearly marked as being read-only.
Here is an example:
{
"swagger": "2.0",
"info": {
"title": "Test API",
"version": "v1-beta"
},
"host": "api.contoso.com",
"schemes": [
"https"
],
"basePath": "/api/v1-beta",
"securityDefinitions": {
"api_key": {
"name": "X-API-KEY",
"type": "apiKey",
"in": "header"
}
},
"security": [
{
"api_key": []
}
],
"consumes": [
"application/json"
],
"produces": [
"application/json"
],
"paths": {
"/things/": {
"post": {
"summary": "Create new things.",
"parameters": [
{
"name": "things",
"in": "body",
"required": true,
"schema": {
"type": "array",
"items": {
"type": "object",
"required": [
"name",
"description"
],
"properties": {
"id": {
"type": "integer",
"minimum": 1,
"readOnly": true,
"description": "Unique identifier of this thing"
},
"name": {
"description": "The name of the thing",
"type": "string",
"minLength": 1,
"maxLength": 64
},
"description": {
"type": "string",
"maxLength": 164,
"description": "Human-readable description of this thing."
}
},
"minItems": 1
},
"description": "An array of things to add to the database."
}
],
"responses": {
"200": {
"description": "Things successfully inserted"
},
"400": {
"description": "The request violated the specification and was rejected.",
"schema": {
"type": "string",
"description": "Human-readable description of the validation failure that led to the error. Only the first error found is reported."
}
},
"403": {
"description": "Operation was not allowed due to an invalid API key, insufficient privileges or trying to reference an entity that does not exist. We have purposedfully combined non-existance and lack of privileges into this error code to avoid enumeration attacks.",
"schema": {
"type": "string",
"description": "Human-readable description of the causes of the error."
}
},
"415": {
"description": "Operation failed because the content-type of the data submitted in the request body is not application/json.",
"schema": {
"type": "string",
"description": "Human-readable description of the causes of the error."
}
}
}
}
}
}
}
This doesn't seem to output API prefix URL (basePath):
swagger: '2.0'
host: api.uber.com
schemes:
- https
basePath: /v1
paths:
...
This issue is there to collect ideas about interactive features in future bootprint-versions.
React
A declarative, efficient, and flexible JavaScript library for building user interfaces.
🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
Typescript
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
An Open Source Machine Learning Framework for Everyone
Django
The Web framework for perfectionists with deadlines.
Laravel
A PHP framework for web artisans
Bring data to life with SVG, Canvas and HTML. 📊📈🎉
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
Some thing interesting about web. New door for the world.
A server is a program made to process requests and deliver data to clients.
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
Some thing interesting about visualization, use data art
Some thing interesting about game, make everyone happy.
Facebook
We are working to build community through open source technology. NB: members must have two-factor auth.
Microsoft
Open source projects and samples from Microsoft.
Google
Google ❤️ Open Source for everyone.
Alibaba
Alibaba Open Source for everyone
D3
Data-Driven Documents codes.
Tencent
China tencent open source team.