fliptoo / swagger-express Goto Github PK

please update dependent packages

I have specified my api doc as below but in this app-x-tk is being sent as query param instead of header

/**

• @Swagger
• path: /v1/api/getDetails
• operations:
• • httpMethod: GET
• summary: Get details
• responseClass: resClass
• nickname: getDetails
• consumes:

• - application/json
  

• produces:

• - application/json
  

• parameters:
• • name: id

• paramType: query
  

• required: true
  

• dataType: string
  

• • name: app-x-tk

• paramType: header
  

• required: true
  

• dataType: string
  

*/

I saw app.configure() was used in README.md and example/app.js. But in the latest version of Express (4.x), The configure function was removed.

https://expressjs.com/en/guide/migrating-4.html#other-changes

The app.configure() function has been removed. Use the process.env.NODE_ENV or app.get('env') function to detect the environment and configure the app accordingly.

What is the format for putting example responses into the inline documentation?

I am getting this error in swagger UI

"Please specify the protocol for /api-docs.json?api_key=special-key"

I have setup the swagger in express as shown in example.

Please help.

How can I specify type: array in some model.

For example, I want to specify something like below
`
/**

• @Swagger
• models:
• ModelA:

• id: ModelA
  

• properties:
  

•   prop1:
  

•     type: Integer
  

•   prop2:
  

•     type: Array[ModelB]
  

• ModelB:

• id: ModelB
  

• properties:
  

•   prop3:
  

•     type: String
  

•   prop4:
  

•     type: String
  

*/
`

When I leave out basePath parameter I get the following error:

node_modules/swagger-express/lib/swagger-express/index.js:228
throw new Error(''basePath' is required.')

Possible to set basePath dynamically? This would make it much easier to deploy to different domains.

npm current holds version 1.0.1, can you please build version 1.0.2 and publish it?

If I want to have the Swagger UI at http://example.com/docs/ but my API lives at http://api.example.com then I'll need to set the Access-Control-Allow-Origin: example.com header for the /api-docs/ routes. Otherwise, the AJAX requests won't work.

Looking at the example, I do not see api-docs.json. I thought that this piece of software produces api-docs.json based on yml or jsdocs. Is there some magic involved here which I do not understand? Can someone please clarify how the example works without having api-docs.json?

Is there no way to auto generate the yaml file in order to get the swagger documentation, I was referred to this page in order to accomplish this but w=after reading the documentation I had no success. I just don't really know anything about creating the yaml file so if I need to learn it I will just wanted to see if there was an easier way first.

Hi,

I am trying to write a code for File Download, which is a zip file.

This is my YAML file:

produces:
  - application/zip

/library/getacitemspackage:
  # This is the controller for getting the acitem and all its internal references as a deep package for the seamless delivery
    x-swagger-router-controller: library_get_acitems_package
    # this is a post method verb of the api service call
    post:
      summary: The API does the zip of all the given acitems and brings all the deep copy references packages from the cloud library
      description: The API does the zip of all the given acitems and brings all the deep copy references packages from the cloud library
      operationId: libraryGetAcitemsPackage
      parameters:
        - name: acitemsList
          in: body
          description: The list of all the acitems for which the package needs to be delivered as a zip
          schema:
            type: object
      responses:
        "200":
          description: Success
          schema:            
            type: object
        default:
          description: Error
          schema:
            $ref: "#/definitions/ErrorResponse"

the code sends a zip stream in the response and the it is failing as response validation failed for schema validation

            var archive = archiver('zip');          
            var totalAcitemListArray = totalAcitemList.toArray();           
            for (var index = 0; index < totalAcitemListArray.length; index++) {
                archive.append(fs.createReadStream(path.join(root_directory, totalAcitemListArray[index])), { name:totalAcitemListArray[index] });
            }           
            archive.finalize();
            archive.on('error', function(err) {
                response.status(500).send({error: err.message});
            });
            response.send('acitemsPackage.zip');            
            archive.pipe(response);

Hi
Is it possible to set api key as barear token ?
Regards,
Michal

/**

• @Swagger
• path: /get_city_list
• operations:
• • httpMethod: POST

•  summary: provide supplierId and accessToken
  

•  notes: Returns a list of city corresponding to its supplierId
  

•  responseClass: Supplier
  

•  nickname: getCityList
  

•  consumes: 
  

•    - text/html
  

•  parameters:
  

•    - name: accessToken
  

•      description: Your AccessToken
  

•      paramType : body
  

•      required: true
  

•      dataType: string
  

•    - name: supplierId
  

•      description: Your SupplierID
  

•      paramType : body
  

•      required: true
  

•      dataType: string
  

  */

Would it be possible to update the dependencies? Namely Express 3.5.1 which has deprecated dependencies that have been resolved in newer versions of express.

Getting this warning when specifying a YAML file in the apis: array:

Direct yaml files load via require() is deprecated! Use safeLoad() instead.

What is the format for putting example responses into the inline documentation?
This is more for returning an object rather than, a message.

Demo looks like broken (also see DownForEveryOneOrJustMe.com).

First of all, nice job with your contribution, it's awesome.
I'd like to know how to add response messages with status codes to the documentation. I've seen https://github.com/wordnik/swagger-core/wiki/Response-Messages but I need an example more specific for your distribution.

Thanks a lot

Is it possible to specify an array of objects as a result of an operation?

Running http://localhost:3000/, I only see:

Where is the Swagger UI?

More specifically:

/**
 * @swagger
 * resourcePath: /api
 * description: All about API
 */

/**
 * @swagger
 * path: /login
 * operations:
 *   -  httpMethod: POST
 *      summary: Login with username and password
 *      notes: Returns a user based on username
 *      responseClass: User
 *      nickname: login
 *      consumes: 
 *        - text/html
 * ...
 */

If this is what I have, and try to use swagger-ui, login will try to call /login, and not /api/login. That feels a bit wierd to me, but I wanted to make sure if that is intended before perhaps submitting a patch that prepends resourcePath...

Sample setting

// src/swagger/index.js
const swaggerSettings = {
  apiVersion: '1.0.0',
  swaggerVersion: '1.0',
  swaggerURL: '/docs',
  swaggerJSON: '/api.json',
  swaggerUI: resolve(__dirname, 'public'),
  basePath: 'http://localhost:9001',
  apis: [
    '../user/routes.js'
  ]
};

my project tree

src/
  swagger/
    index.js
  user/
    index.js
    routes.js
    controllers.js

asap open the /api.json URL I got a ENOENT: no such file or directory, open './../operator/routes.js' on terminal

Docs only mention swagger 1.0. Does this library support swagger 2.0?

It is a normal practice to deploy REST services behind reverse proxies in production. But swagger-express will fail to work currently. The problem is that swagger json is bound to basePath prefix.

We came up with these fixes which did the job for us:
https://gist.github.com/RomanKisilenko/74ab3ff697696ba7eb07062834e4b022

Hopefully you can integrate these changes and release next version.

Could you publish a new version with the latest changes?

Thanks.