Swagger-UI Maximum call stack size exceeded -> Backreference - swagger

When calling my swagger.json from the swagger-ui I get an error:
Maximum call stack size exceeded
I guess it is because I have
Token which has an owner of Type User
User which has a Token of Type Token
When using the online-version of the swagger editior it can resolve the types. How can I configure swagger to resolve the types correctly?
The full swagger.json
{
"swagger": "2.0",
"info": {
"description": "Descr",
"version": "1.0.0",
"title": "Skeleton"
},
"host": "1.1.1.1:11",
"basePath": "/api",
"tags": [{
"name": "auth"
}
],
"schemes": ["http"],
"paths": {
"/auth/local": {
"post": {
"tags": ["auth"],
"summary": "Authenticates User",
"description": "This auths only local users",
"operationId": "authenticateUser",
"consumes": ["application/json"],
"produces": ["application/json"],
"parameters": [{
"in": "body",
"name": "body",
"required": false,
"schema": {
"$ref": "#/definitions/Credentials"
}
}
],
"responses": {
"200": {
"description": "successful operation",
"schema": {
"$ref": "#/definitions/AuthResponse"
}
}
}
}
},
"/auth/ldap": {
"post": {
"tags": ["auth"],
"operationId": "authenticateLdapUser",
"produces": ["application/json"],
"parameters": [{
"in": "body",
"name": "body",
"required": false,
"schema": {
"$ref": "#/definitions/Credentials"
}
}
],
"responses": {
"default": {
"description": "successful operation"
}
}
}
}
},
"definitions": {
"AuthResponse": {
"type": "object",
"properties": {
"issued": {
"type": "string",
"format": "date-time"
},
"responseType": {
"type": "string",
"enum": ["RESPONSE", "ERROR", "UNAUTHORIZED", "OK"]
},
"responseDescription": {
"type": "string"
},
"accessToken": {
"$ref": "#/definitions/Token"
},
"resourceName": {
"type": "string"
}
}
},
"Note": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"format": "int32"
},
"content": {
"type": "string"
},
"modified": {
"type": "string",
"format": "date-time"
}
}
},
"Token": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"expirationDate": {
"type": "string",
"format": "date-time"
},
"issued": {
"type": "string",
"format": "date-time"
},
"expired": {
"type": "boolean"
},
"owner": {
"$ref": "#/definitions/User"
}
}
},
"User": {
"type": "object",
"properties": {
"username": {
"type": "string"
},
"password": {
"type": "string"
},
"email": {
"type": "string"
},
"displayName": {
"type": "string"
},
"notes": {
"type": "array",
"items": {
"$ref": "#/definitions/Note"
}
},
"accessToken": {
"$ref": "#/definitions/Token"
}
}
},
"Credentials": {
"type": "object",
"properties": {
"user": {
"type": "string"
},
"password": {
"type": "string"
}
}
}
}
}

I have the same problem and I removed format: date-time and the error is gone.
Still I don't know what causes the error. But without that format everything goes ok.

In FastAPI which uses Swagger UI, I was receiving the same error. I updated the FastAPI package to get the last version of Swagger UI and then set the value of 'syntaxHighlight' to False, like below:
app = FastAPI(swagger_ui_parameters={'syntaxHighlight': False})
Just search how you can set this param directly in Swagger UI. This may fix your issue.

Related

OpenAPI v3, how to hide objects in "Schemas" section

I'm using OpenAPI v3 to create my API docs and having them hosted on app.swaggerhub.com
Is there a way to hide an item from showing up in the Schemas section at the bottom? The real API has dozens of Schema objects, so it'd be very helpful to hide some of them.
Example:
Running this on https://editor-next.swagger.io/
{
"openapi": "3.0.3",
"info": {
"title": "Swagger Petstore - OpenAPI 3.0",
"description": "example",
"version": "1.0.11"
},
"servers": [
{
"url": "https://petstore3.swagger.io/api/v3"
}
],
"paths": {
"/pet": {
"post": {
"summary": "Add a new pet to the store",
"description": "Add a new pet to the store",
"operationId": "addPet",
"requestBody": {
"description": "Create a new pet in the store",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Pet"
}
},
"application/xml": {
"schema": {
"$ref": "#/components/schemas/Pet"
}
},
"application/x-www-form-urlencoded": {
"schema": {
"$ref": "#/components/schemas/Pet"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "Successful operation",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Pet"
}
},
"application/xml": {
"schema": {
"$ref": "#/components/schemas/Pet"
}
}
}
}
}
}
}
},
"components": {
"schemas": {
"Order": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"format": "int64",
"example": 10
},
"petId": {
"type": "integer",
"format": "int64",
"example": 198772
},
"quantity": {
"type": "integer",
"format": "int32",
"example": 7
},
"shipDate": {
"type": "string",
"format": "date-time"
},
"status": {
"type": "string",
"description": "Order Status",
"example": "approved",
"enum": [
"placed",
"approved",
"delivered"
]
},
"complete": {
"type": "boolean"
}
},
"xml": {
"name": "order"
}
},
"Customer": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"format": "int64",
"example": 100000
},
"username": {
"type": "string",
"example": "fehguy"
},
"address": {
"type": "array",
"xml": {
"name": "addresses",
"wrapped": true
},
"items": {
"$ref": "#/components/schemas/Address"
}
}
},
"xml": {
"name": "customer"
}
},
"Address": {
"type": "object",
"properties": {
"street": {
"type": "string",
"example": "437 Lytton"
},
"city": {
"type": "string",
"example": "Palo Alto"
},
"state": {
"type": "string",
"example": "CA"
},
"zip": {
"type": "string",
"example": "94301"
}
},
"xml": {
"name": "address"
}
},
"Category": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"format": "int64",
"example": 1
},
"name": {
"type": "string",
"example": "Dogs"
}
},
"xml": {
"name": "category"
}
},
"User": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"format": "int64",
"example": 10
},
"username": {
"type": "string",
"example": "theUser"
},
"firstName": {
"type": "string",
"example": "John"
},
"lastName": {
"type": "string",
"example": "James"
},
"email": {
"type": "string",
"example": "john#email.com"
},
"password": {
"type": "string",
"example": "12345"
},
"phone": {
"type": "string",
"example": "12345"
},
"userStatus": {
"type": "integer",
"description": "User Status",
"format": "int32",
"example": 1
}
},
"xml": {
"name": "user"
}
},
"Tag": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"format": "int64"
},
"name": {
"type": "string"
}
},
"xml": {
"name": "tag"
}
},
"Pet": {
"required": [
"name",
"photoUrls"
],
"type": "object",
"properties": {
"id": {
"type": "integer",
"format": "int64",
"example": 10
},
"name": {
"type": "string",
"example": "doggie"
},
"category": {
"$ref": "#/components/schemas/Category"
},
"photoUrls": {
"type": "array",
"xml": {
"wrapped": true
},
"items": {
"type": "string",
"xml": {
"name": "photoUrl"
}
}
},
"tags": {
"type": "array",
"xml": {
"wrapped": true
},
"items": {
"$ref": "#/components/schemas/Tag"
}
},
"status": {
"type": "string",
"description": "pet status in the store",
"enum": [
"available",
"pending",
"sold"
]
}
},
"xml": {
"name": "pet"
}
},
"ApiResponse": {
"type": "object",
"properties": {
"code": {
"type": "integer",
"format": "int32"
},
"type": {
"type": "string"
},
"message": {
"type": "string"
}
},
"xml": {
"name": "##default"
}
}
},
"requestBodies": {
"Pet": {
"description": "Pet object that needs to be added to the store",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Pet"
}
},
"application/xml": {
"schema": {
"$ref": "#/components/schemas/Pet"
}
}
}
},
"UserArray": {
"description": "List of user object",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/User"
}
}
}
}
}
},
"securitySchemes": {
"petstore_auth": {
"type": "oauth2",
"flows": {
"implicit": {
"authorizationUrl": "https://petstore3.swagger.io/oauth/authorize",
"scopes": {
"write:pets": "modify pets in your account",
"read:pets": "read your pets"
}
}
}
},
"api_key": {
"type": "apiKey",
"name": "api_key",
"in": "header"
}
}
}
}
...this gets generated:
In this example, I'd like to hide a few of the schema items from view (like Customer or Address).
Note: I'm not self-hosting, so I'm hoping there's a tag I can put into the YAML or JSON.
Thanks,
Ryan

api-doc generated by Springfox not work with swagger-codegen

I'm testing if I can use the api-doc generated by springfox to generate Java client code through swagger-codegen.
I use the boot-swagger module from springfox-demos and the generated api-doc looks like below (pretty formatted)
{
"swagger": "2.0",
"info": {
"description": "Lorem Ipsum is simply dummy text of the printing and typesetting industry. Lorem Ipsum has been the industry's standard dummy text ever since the 1500s, when an unknown printer took a galley of type and scrambled it to make a type specimen book. It has survived not only five centuries, but also the leap into electronic typesetting, remaining essentially unchanged. It was popularised in the 1960s with the release of Letraset sheets containing Lorem Ipsum passages, and more recently with desktop publishing software like Aldus PageMaker including versions of Lorem Ipsum.",
"version": "2.0",
"title": "Springfox petstore API",
"termsOfService": "http://springfox.io",
"contact": {
"name": "springfox"
},
"license": {
"name": "Apache License Version 2.0",
"url": "https://github.com/springfox/springfox/blob/master/LICENSE"
}
},
"host": "localhost:8080",
"basePath": "/springfox",
"tags": [
{
"name": "category-controller",
"description": "Category Controller"
}
],
"paths": {
"/categories{?categories}": {
"post": {
"tags": [
"category-controller"
],
"summary": "map",
"operationId": "mapUsingPOST",
"consumes": [
"application/json"
],
"produces": [
"*/*"
],
"parameters": [
{
"name": "categories",
"in": "query",
"description": "categories",
"required": false,
"type": "array",
"items": {
"type": "string"
},
"collectionFormat": "multi"
}
],
"responses": {
"200": {
"description": "OK",
"schema": {
"type": "array",
"items": {
"type": "string",
"enum": [
"ONE",
"TWO",
"THREE"
]
}
}
},
"201": {
"description": "Created"
},
"401": {
"description": "Unauthorized"
},
"403": {
"description": "Forbidden"
},
"404": {
"description": "Not Found"
}
}
}
},
"/category/Resource{?someEnum}": {
"get": {
"tags": [
"category-controller"
],
"summary": "search",
"operationId": "searchUsingGET",
"produces": [
"*/*"
],
"parameters": [
{
"name": "someEnum",
"in": "query",
"description": "someEnum",
"required": true,
"type": "string",
"enum": [
"ONE",
"TWO",
"THREE"
]
}
],
"responses": {
"200": {
"description": "OK",
"schema": {
"type": "string"
}
},
"401": {
"description": "Unauthorized"
},
"403": {
"description": "Forbidden"
},
"404": {
"description": "Not Found"
}
}
}
},
"/category/map": {
"get": {
"tags": [
"category-controller"
],
"summary": "map",
"operationId": "mapUsingGET",
"produces": [
"*/*"
],
"responses": {
"200": {
"description": "OK",
"schema": {
"type": "object",
"additionalProperties": {
"type": "object",
"additionalProperties": {
"$ref": "#/definitions/Pet"
}
}
}
},
"401": {
"description": "Unauthorized"
},
"403": {
"description": "Forbidden"
},
"404": {
"description": "Not Found"
}
}
}
},
"/category/{id}": {
"post": {
"tags": [
"category-controller"
],
"summary": "someOperation",
"operationId": "someOperationUsingPOST",
"consumes": [
"application/json"
],
"produces": [
"*/*"
],
"parameters": [
{
"name": "id",
"in": "path",
"description": "id",
"required": true,
"type": "integer",
"format": "int64"
},
{
"in": "body",
"name": "userId",
"description": "userId",
"required": true,
"schema": {
"type": "integer",
"format": "int32"
}
}
],
"responses": {
"200": {
"description": "OK"
},
"201": {
"description": "Created"
},
"401": {
"description": "Unauthorized"
},
"403": {
"description": "Forbidden"
},
"404": {
"description": "Not Found"
}
}
}
},
"/category/{id}/map{?test}": {
"post": {
"tags": [
"category-controller"
],
"summary": "map",
"operationId": "mapUsingPOST_1",
"consumes": [
"application/json"
],
"produces": [
"*/*"
],
"parameters": [
{
"name": "id",
"in": "path",
"description": "id",
"required": true,
"type": "string"
},
{
"name": "test",
"in": "query",
"description": "test",
"required": true,
"items": {
"type": "object",
"additionalProperties": {
"type": "string"
}
}
}
],
"responses": {
"200": {
"description": "OK"
},
"201": {
"description": "Created"
},
"401": {
"description": "Unauthorized"
},
"403": {
"description": "Forbidden"
},
"404": {
"description": "Not Found"
}
}
}
},
"/category/{id}/{userId}": {
"post": {
"tags": [
"category-controller"
],
"summary": "ignoredParam",
"operationId": "ignoredParamUsingPOST",
"consumes": [
"application/json"
],
"produces": [
"*/*"
],
"parameters": [
{
"name": "id",
"in": "path",
"description": "id",
"required": true,
"type": "integer",
"format": "int64"
}
],
"responses": {
"200": {
"description": "OK"
},
"201": {
"description": "Created"
},
"401": {
"description": "Unauthorized"
},
"403": {
"description": "Forbidden"
},
"404": {
"description": "Not Found"
}
}
}
}
},
"definitions": {
"Category": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"format": "int64"
},
"name": {
"type": "string"
}
},
"title": "Category"
},
"Map«string,Pet»": {
"type": "object",
"title": "Map«string,Pet»",
"additionalProperties": {
"$ref": "#/definitions/Pet"
}
},
"Pet": {
"type": "object",
"properties": {
"category": {
"$ref": "#/definitions/Category"
},
"id": {
"type": "integer",
"format": "int64"
},
"identifier": {
"type": "integer",
"format": "int64"
},
"name": {
"type": "string"
},
"photoUrls": {
"type": "array",
"items": {
"type": "string"
}
},
"status": {
"type": "string",
"description": "pet status in the store",
"allowEmptyValue": false,
"enum": [
"available",
"pending",
"sold"
]
},
"tags": {
"type": "array",
"items": {
"$ref": "#/definitions/Tag"
}
}
},
"title": "Pet"
},
"Tag": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"format": "int64"
},
"name": {
"type": "string"
}
},
"title": "Tag"
}
}
}
The code generation failed and it looks like the api-doc.json does not even fit for swagger specification.
I pasted the code into swagger editor, and it complains for a lot of errors such as
Semantic error at paths./categories{?categories}
Query strings in paths are not allowed.
Jump to line 18
So is it possible to generate client code from the api-doc.json generated by Springfox?
After reading the document of Springfox Reference Documentation, I have solved this issue!
Format like below is because by default springfox applies RFC 6570
./categories{?categories}
3.2. Configuration explained
An example of this would be two apis: First, http://example.org/findCustomersBy?name=Test to find customers by name. Per RFC 6570, this would be represented as http://example.org/findCustomersBy{?name}. Second, http://example.org/findCustomersBy?zip=76051 to find customers by zip. Per RFC 6570, this would be represented as http://example.org/findCustomersBy{?zip}.
One more issue I didn't mention in the question:
"Map«string,Pet»": { // The generated JSON contains special characters
"type": "object",
"title": "Map«string,Pet»",
"additionalProperties": {
"$ref": "#/definitions/Pet"
}
}
The document clearly mentioned the swagger-codegen situation:
6.8.3. Changing how Generic Types are Named
By default, types with generics will be labeled with '\u00ab'(<<), '\u00bb'(>>), and commas. This can be problematic with things like swagger-codegen. You can override this behavior by implementing your own GenericTypeNamingStrategy. For example, if you wanted List to be encoded as 'ListOfString' and Map to be encoded as 'MapOfStringAndObject' you could set the forCodeGeneration customization option to true during plugin customization:
docket.forCodeGeneration(true|false);
To summary, when we generate the docket in springfox for swagger-codegen, we need to specify the following switches:
new Docket(DocumentationType.SWAGGER_2)
.forCodeGeneration(true)
.enableUrlTemplating(false)

Swagger file with warning

Swagger file is working as expected with warnig.
{
'swagger': "2.0",
"info": {
"version": "3.0",
"title": "Sample Service",
},
"schemes": [ "http" ],
"host": "sampleservice.azurewebsites.net",
"paths": {
"/": {
"post": {
"summary": "Sample service",
"description": "sample service",
"parameters": [
{
"name": "Input",
"in": "body",
"description": "valid input",
"schema": {
"type": "object",
"properties": {
"MainAttr-1": {
"required": [ "Attr-1" ],
"type": "object",
"properties": {
"Attr-1": {
"description": "Attr-1",
"required": true,
"type": "string"
},
"Attr-2": {
"description": "Attr-2",
"required": false,
"type": "string"
},
"Attr-3": {
"description": "Attr-3",
"required": false,
"type": "boolean"
},
"Attr-4": {
"description": "Attr-4",
"required": false,
"type": "boolean"
},
"Attr-5": {
"description": "Attr-5",
"required": false,
"type": "string"
}
}
},
"MainAttr-2": {
"type": "array",
"items": {
"type": "object",
"required": [ "Attr-1", "Attr-3", "Attr-5", "Attr-8" ],
"properties": {
"Attr-1": {
"description": "Attr-1",
"required": true,
"type": "string"
},
"Attr-2": {
"description": "Attr-2",
"required": false,
"type": "string"
},
"Attr-3": {
"description": "Attr-3",
"required": true,
"type": "boolean"
},
"Attr-4": {
"description": "Attr-4",
"required": false,
"type": "boolean"
},
"Attr-5": {
"description": "Attr-5",
"required": true,
"type": "string"
},
"Attr-6": {
"description": "Attr-6",
"required": false,
"type": "string"
},
"Attr-7": {
"description": "Attr-7",
"required": false,
"type": "string"
},
"Attr-8": {
"description": "Attr-8",
"required": true,
"type": "string"
}
}
}
}
}
}
}
],
"responses": {
"200": {
"description": "success"
}
}
}
}
}
}
Issue-1) Warning should be removed
Issue-2) Attr-3 in "MainAttr-2" is boolean type attribute and it is required. But when i am selecting 'false' from the dropdown, it is treating as invalid input. It treats only 'true' as valid input. (Any Boolean attribute which is required behaving like this)
Due this warning i am unable to deliver the code.
Thanks in advance.
In the beginning, change 'swagger' to "swagger". JSON requires double quotes around strings.
Remove extra comma at the end of:
"title": "Sample Service",
Remove the required attribute from ALL property definitions (Attr-1 to Attr-8) and use the required list at the object level instead (under MainAttr-1 and MainAttr-2).
"MainAttr-1": {
"required": [ "Attr-1" ], <-- list the required properties in this array
"type": "object",
"properties": {
"Attr-1": {
"description": "Attr-1",
"required": true, <-- remove this
"type": "string"
},
Other than that your spec is fine.

Swagger: Common response/payload object but different data defined per API?

What is the best way to represent a generic response/payload object that has basic fields such as message, total elements, data, and status? Where the variability between each API is the data element. For instance, one API could be for permissions, so the data element would hold an array of permissions. But for another API, it would hold a different array of object types. My main goal is to have reuse with a payload object and to define the next "layer" of actual data.
I want to be able to define a data type that's generic - like a "response" that has basic fields but I want to be able to further define that content for each API (data containing permissions or roles or whatever).
Here are some JSON samples of what's been attempted but isn't rendering the way we would expect it to in Swagger UI (i.e. a flat structure of 4 elements with data defined per the API).
Example 1 - composition:
{
"swagger": "2.0",
"host": "localhost:8888",
"info": {
"version": "0.0.1",
"title": "API"
},
"paths": {
"/permissions": {
"get": {
"description": "Returns all permissions",
"operationId": "getPermissions",
"produces": [
"application/json"
],
"responses": {
"200": {
"description": "success",
"schema": {
"$ref": "#/definitions/permissionResponse"
}
}
}
}
}
},
"definitions": {
"response": {
"type": "object",
"properties": {
"message": {
"type": "string",
"description": "A string indicating the response from the server."
},
"totalElements": {
"type": "integer",
"format": "int64",
"description": "The number of items retrieved."
},
"status": {
"type": "string",
"description": "A string indicating the response from the server."
}
}
},
"permissionResponse": {
"allOf": [
{
"$ref": "#/definitions/response"
}, {
"type": "object",
"properties": {
"data": {
"type": "array",
"description": "The collection of items returned from the API request.",
"items": {
"$ref": "#/definitions/permission"
}
}
}
}
]
},
"permission": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"format": "int64",
"description": "Unique identifier representing a specific permission."
},
"label": {
"type": "string",
"description": "The label of a permission."
},
"description": {
"type": "string",
"description": "A description of the permission."
},
"active": {
"type": "boolean",
"description": "A flag indicating whether a permission is active."
}
},
"required": [
"id",
"label",
"description",
"active"
]
}
}
}
Example 2 - composition variation:
{
"swagger": "2.0",
"host": "localhost:8888",
"info": {
"version": "0.0.1",
"title": "API"
},
"paths": {
"/permissions": {
"get": {
"description": "Returns all permissions",
"operationId": "getPermissions",
"produces": [
"application/json"
],
"responses": {
"200": {
"description": "success",
"schema": {
"$ref": "#/definitions/permissionResponse"
}
}
}
}
}
},
"definitions": {
"response": {
"type": "object",
"properties": {
"message": {
"type": "string",
"description": "A string indicating the response from the server."
},
"totalElements": {
"type": "integer",
"format": "int64",
"description": "The number of items retrieved."
},
"status": {
"type": "string",
"description": "A string indicating the response from the server."
}
}
},
"permissionResponse": {
"allOf": [
{
"$ref": "#/definitions/response"
}],
"type": "object",
"properties": {
"data": {
"type": "array",
"description": "The collection of items returned from the API request.",
"items": {
"$ref": "#/definitions/permission"
}
}
}
},
"permission": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"format": "int64",
"description": "Unique identifier representing a specific permission."
},
"label": {
"type": "string",
"description": "The label of a permission."
},
"description": {
"type": "string",
"description": "A description of the permission."
},
"active": {
"type": "boolean",
"description": "A flag indicating whether a permission is active."
}
},
"required": [
"id",
"label",
"description",
"active"
]
}
}
Example 3 - additional properties:
{
"swagger": "2.0",
"host": "localhost:8888",
"info": {
"version": "0.0.1",
"title": "API"
},
"paths": {
"/permissions": {
"get": {
"description": "Returns all permissions",
"operationId": "getPermissions",
"produces": [
"application/json"
],
"responses": {
"200": {
"description": "success",
"schema": {
"$ref": "#/definitions/permissionResponse"
}
}
}
}
}
},
"definitions": {
"response": {
"type": "object",
"properties": {
"message": {
"type": "string",
"description": "A string indicating the response from the server."
},
"totalElements": {
"type": "integer",
"format": "int64",
"description": "The number of items retrieved."
},
"status": {
"type": "string",
"description": "A string indicating the response from the server."
}
}
},
"permissionResponse": {
"type": "object",
"properties": {
"data": {
"type": "array",
"description": "The collection of items returned from the API request.",
"items": {
"$ref": "#/definitions/permission"
}
}
},
"additionalProperties": {
"$ref": "#/definitions/response"
}
},
"permission": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"format": "int64",
"description": "Unique identifier representing a specific permission."
},
"label": {
"type": "string",
"description": "The label of a permission."
},
"description": {
"type": "string",
"description": "A description of the permission."
},
"active": {
"type": "boolean",
"description": "A flag indicating whether a permission is active."
}
},
"required": [
"id",
"label",
"description",
"active"
]
}
}
Example 1 renders well with swagger2markup showing the consolidated view of the data with the other 3 elements and having a permission array. However, with Swagger UI, it renders it differently, separating the objects out.
Markup rendered:
Swagger UI rendered
Swagger UI rendered - expanded

Load HTML into Swagger Docs Implementation Notes

I'm attempting to display HTML for my implementation notes for a given endpoint using Swagger Docs. Below, I've typed out the HTML as a string, but I love to load these in as a module of some sort, so that I can simply edit HTML files separately.
I couldn't find an answer in the Google Group and I'd like to see if this is something that is already solved before I create some sort of grunt plug-in to handle it.
Here's my current code:
module.exports = function (swagger) {
var docs = swagger.createResource("/docs/endpoint");
docs.get('/endpoint', "Endpoint Title", {
"summary": "Some description about the endpoint",
"notes": " \
<h2>Getting Started with Endpoint:</h2> \
<br /><p>This endpoint some some really important things.</p> \
",
"type": "",
"nickname": "",
"parameters": [
{
"name": "apiKey",
"description": "The API Key for the requesting application",
"required": true,
"type": "string",
"paramType":"query"
}]
[...]
Is there a cleaner way to implement this?
Swagger 2.0 adds some more flexibility with rich documentation.
One way, is the ability to add markdown tags (GFM flavor) to the description fields.
Another way, is to use the externalDocs property where applicable to add an external documentation resource. An example for it would be:
{
"swagger": "2.0",
"info": {
"version": "1.0.0",
"title": "Swagger Petstore",
"description": "A sample API that uses a petstore as an example to demonstrate features in the swagger-2.0 specification",
"termsOfService": "http://helloreverb.com/terms/",
"contact": {
"name": "Wordnik API Team",
"email": "foo#example.com",
"url": "http://madskristensen.net"
},
"license": {
"name": "MIT",
"url": "http://github.com/gruntjs/grunt/blob/master/LICENSE-MIT"
}
},
"externalDocs": {
"description": "find more info here",
"url": "https://helloreverb.com/about"
},
"host": "petstore.swagger.wordnik.com",
"basePath": "/api",
"schemes": [
"http"
],
"consumes": [
"application/json"
],
"produces": [
"application/json"
],
"paths": {
"/pets": {
"get": {
"description": "Returns all pets from the system that the user has access to",
"operationId": "findPets",
"externalDocs": {
"description": "find more info here",
"url": "https://helloreverb.com/about"
},
"produces": [
"application/json",
"application/xml",
"text/xml",
"text/html"
],
"parameters": [
{
"name": "tags",
"in": "query",
"description": "tags to filter by",
"required": false,
"type": "array",
"items": {
"type": "string"
},
"collectionFormat": "csv"
},
{
"name": "limit",
"in": "query",
"description": "maximum number of results to return",
"required": false,
"type": "integer",
"format": "int32"
}
],
"responses": {
"200": {
"description": "pet response",
"schema": {
"type": "array",
"items": {
"$ref": "#/definitions/pet"
}
}
},
"default": {
"description": "unexpected error",
"schema": {
"$ref": "#/definitions/errorModel"
}
}
}
},
"post": {
"description": "Creates a new pet in the store. Duplicates are allowed",
"operationId": "addPet",
"produces": [
"application/json"
],
"parameters": [
{
"name": "pet",
"in": "body",
"description": "Pet to add to the store",
"required": true,
"schema": {
"$ref": "#/definitions/newPet"
}
}
],
"responses": {
"200": {
"description": "pet response",
"schema": {
"$ref": "#/definitions/pet"
}
},
"default": {
"description": "unexpected error",
"schema": {
"$ref": "#/definitions/errorModel"
}
}
}
}
},
"/pets/{id}": {
"get": {
"description": "Returns a user based on a single ID, if the user does not have access to the pet",
"operationId": "findPetById",
"produces": [
"application/json",
"application/xml",
"text/xml",
"text/html"
],
"parameters": [
{
"name": "id",
"in": "path",
"description": "ID of pet to fetch",
"required": true,
"type": "integer",
"format": "int64"
}
],
"responses": {
"200": {
"description": "pet response",
"schema": {
"$ref": "#/definitions/pet"
}
},
"default": {
"description": "unexpected error",
"schema": {
"$ref": "#/definitions/errorModel"
}
}
}
},
"delete": {
"description": "deletes a single pet based on the ID supplied",
"operationId": "deletePet",
"parameters": [
{
"name": "id",
"in": "path",
"description": "ID of pet to delete",
"required": true,
"type": "integer",
"format": "int64"
}
],
"responses": {
"204": {
"description": "pet deleted"
},
"default": {
"description": "unexpected error",
"schema": {
"$ref": "#/definitions/errorModel"
}
}
}
}
}
},
"definitions": {
"pet": {
"required": [
"id",
"name"
],
"externalDocs": {
"description": "find more info here",
"url": "https://helloreverb.com/about"
},
"properties": {
"id": {
"type": "integer",
"format": "int64"
},
"name": {
"type": "string"
},
"tag": {
"type": "string"
}
}
},
"newPet": {
"allOf": [
{
"$ref": "pet"
},
{
"required": [
"name"
],
"properties": {
"id": {
"type": "integer",
"format": "int64"
}
}
}
]
},
"errorModel": {
"required": [
"code",
"message"
],
"properties": {
"code": {
"type": "integer",
"format": "int32"
},
"message": {
"type": "string"
}
}
}
}
}

Resources