Related
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)
I'm having difficulty accessing data in a collection, via PowerApps.
I create the collection with this:
Collect(coll15,mt.GetAnswers("3b....da","application/json",{question:"eco"}))
Using Developer Tools -> Network tab -> Response body - the following JSON data is returned:
{
"answers": [
{
"answer": "This is the answer",
"questions": [
"Private vehicle eco renewal"
],
"score": 82.901087775826454
}
]
}
The collection is created.
I then add a gallery control to my page - however the only options I have to bind to the labels are: ThisItem.Value
If I try to enter ThisItem.Value.answer I get the error: Invalid use of '.'
If I enter ThisItem.answers.answer I get the error: Invalid name
This is the swagger file:
{
"swagger": "2.0",
"info": {
"version": "1.0.0",
"title": "mt",
"description": "mt"
},
"host": "westus.api.cognitive.microsoft.com:443",
"basePath": "/",
"schemes": [
"https"
],
"consumes": [],
"produces": [
"application/json"
],
"paths": {
"/qnamaker/v2.0/knowledgebases/eeeee.....eeeee/generateAnswer": {
"post": {
"summary": "GetAnswers",
"description": "Get answers from qna",
"operationId": "GetAnswers",
"parameters": [
{
"name": "body",
"in": "body",
"schema": {
"type": "object",
"properties": {
"question": {
"type": "string",
"description": "question",
"x-ms-summary": "question",
"title": "question",
"x-ms-visibility": ""
}
},
"default": {
"question": "hi"
},
"required": [
"question"
]
},
"required": true
}
],
"responses": {
"default": {
"description": "default",
"schema": {
"type": "string"
}
}
}
}
}
},
"definitions": {},
"parameters": {},
"responses": {},
"securityDefinitions": {
"api_key": {
"type": "apiKey",
"in": "header",
"name": "Ocp-Apim-Subscription-Key"
}
},
"security": [
{
"oauth2_auth": [
"Offline-Access"
]
}
],
"tags": []
}
Is there any way for me to access the answer text within the collection?
Thanks for any help,
Mark
The problem is that the response type for the operation in the connector definition is string:
"responses": {
"default": {
"description": "default",
"schema": {
"type": "string"
}
}
}
But your response is an object instead. If you update your custom connector to use a typed object instead, you should be able to access the response from the operation. Something along the lines of the schema below:
"responses": {
"default": {
"description": "default",
"schema": {
"type": "object",
"properties": {
"answers": {
"type": "array",
"items": {
"type": "object",
"properties": {
"answer": {
"type": "string"
},
"questions": {
"type": "array",
"items": {
"type": "string"
}
},
"score": {
"type": "number",
"format": "float"
}
}
}
}
}
}
}
},
Notice that in the portal (web.powerapps.com), if you go to your custom connector definition, and select "Edit", you can go to the operation, and select the response you want to edit:
And then use the "Import from sample" option
With that, if you enter an example of a response from the API, it will create the schema for you (which is similar to the one I have above).
I am newer in Swagger tool. I try to test my Restfull application with swagger editor. I used basic authentication to access the web service.
In the Swagger-UI, the preview looks correct, i.e. Content-Type: application/json and the json is in the body.But When I send GET request from the Swagger editor to server, I got an error.
ERROR Server not found or an error occurred
My Swagger
{
"swagger": "2.0",
"info": {
"version": "1.0.0",
"title": "Swagger Petstore (Simple)",
"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": "Swagger API team",
"email": "abc#gmail.com",
"url": "http://avfg.com"
},
"license": {
"name": "MIT",
"url": "http://opensource.org/licenses/MIT"
}
},
"host": "127.0.0.1:8xxx",
"basePath": "/v1",
"schemes": [
"http"
],
"consumes": [
"application/json"
],
"produces": [
"application/json"
],
"paths": {
"/facedetect/{username}/{albumname}/{imagename}": {
"get": {
"description": "Returns all pets from the system that the user has access to",
"operationId": "findPets",
"produces": [
"application/json",
"application/xml"
],
"parameters": [
{
"name": "username",
"in": "path",
"description": "tags to filter by",
"required": true,
"type": "string"
},
{
"name": "albumname",
"in": "path",
"description": "maximum number of results to return",
"required": true,
"type": "string"
},
{
"name": "imagename",
"in": "path",
"description": "maximum number of results to return",
"required": true,
"type": "string"
}
],
"responses": {
"200": {
"description": "pet response",
"schema": {
"type": "array",
"items": {
"$ref": "#/definitions/pet"
}
}
},
"default": {
"description": "unexpected error",
"schema": {
"$ref": "#/definitions/errorModel"
}
}
}
}
}
},
"definitions": {
"pet": {
"type": "object",
"required": [
"id",
"name"
],
"properties": {
"id": {
"type": "integer",
"format": "int64"
},
"name": {
"type": "string"
},
"tag": {
"type": "string"
}
}
},
"errorModel": {
"type": "object",
"required": [
"code",
"message"
],
"properties": {
"code": {
"type": "integer",
"format": "int32"
},
"message": {
"type": "string"
}
}
}
}
}
Please help me.
Thanks in advance.
Make sure that you have your server running.
If you have swagger installed, you can do
swagger project start
I got the solution.
Its CORS issue. My browser was blocking cors requests. I have installed a Chrome extension that adds Access-Control-Allow-Origin to outgoing requests.
I had simillar problem
this is CORS, but :
in nodeJS i have set:
app.use(function(req, res, next) {
res.header("Access-Control-Allow-Origin", "*");
res.header('Access-Control-Allow-Headers', 'Origin, X-Requested-With, Content-Type, Accept, Authorization');
res.header('Access-Control-Allow-Methods', 'GET, POST, PUT, UPDATE, DELETE, OPTIONS')
res.header("Content-Type", "application/json");
next();
});
but it helps only when request was without authorization (api-key). To make it works I have to change and use:
const cors = require('cors');
app.use(cors());
hope it is helpfull
We are using swagger 2.0 to document our .Net Web API's which we are hosting in Azure behind Azure API Management. I am having troubles getting the documentation to detail the complex objects that are being posted as part of the body. Azure shows no details about the object at all leaving me to have to document them myself. Below is the json file that I imported into Azure API Management.
{
"swagger": "2.0",
"info": {
"version": "1.0.0",
"title": "Hotel Search",
"description": "The seodecnvewjkl"
},
"basePath": "/v1",
"consumes": [
"application/xml",
"application/json"
],
"produces": [
"application/xml",
"application/json"
],
"schemes": [
"http",
"https"
],
"paths": {
"/hotels/search": {
"post": {
"operationId": "searchCommand",
"description": "Searches for hotels",
"parameters": [
{
"name": "hotelSearchRq",
"in": "body",
"required": true,
"schema": {
"$ref": "#/definitions/HotelSearchRq"
}
}
],
"responses": {
"200": {
"description": "Successful response",
"schema": {
"title": "HotelSearchRs",
"$ref": "#/definitions/HotelSearchRs"
}
},
"400": {
"description": "Bad Request"
},
"404": {
"description": "Unauthorised"
}
}
},
"get": {
"operationId": "searchQuery",
"parameters": [
{
"name": "CorrelationId",
"in": "query",
"type": "string"
}
],
"responses": {
"200": {
"description": "Successful response"
}
}
}
}
},
"definitions": {
"StayDetail": {
"type": "object",
"properties": {
"NumberOfGuests": {
"type": "integer"
},
"CheckinDate": {
"type": "string",
"format": "date",
"description": "the date that the stay starts from"
}
}
},
"HotelSearchCriteria": {
"type": "object",
"properties": {
"MaximumResults": {
"type": "integer",
"format": "int64"
},
"StayDetails": {
"$ref": "#/definitions/StayDetail"
}
}
},
"HotelSearchRq": {
"type": "object",
"properties": {
"CustomerTransactionIdentifier": {
"type": "string",
"description": "The customers transaction identifier"
},
"search_criteria": {
"$ref": "#/definitions/HotelSearchCriteria"
}
}
},
"HotelSearchRs": {
"type": "object"
}
}
}
Azure Api Management operation screen
Can someone please help me with how I can get the body documented automatically from the swagger documentation?
Currently the request and response body information from a Swagger doc are not displayed in the developer portal documentation.
This is no longer the case. Samples and schema are displayed in the developer portal.
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"
}
}
}
}
}