Docs storage directory is constantly being overwritten

[w0rd-driven]

https://github.com/slampenny/Swaggervel/blob/master/src/Jlapp/Swaggervel/routes.php#L24 points to the codepath being hit.

For current Swagger runs via the CLI, it doesn't recreate the output directory at all it just dumps the file. The part of the if statement that passes is the is_writeable($docsDir) which always returns true. This causes the entire directory to be overwritten every generation.

A temporary fix for my deployment issues was to add /storage/docs to the top level .gitignore file but I'd rather it be like all the other storage directories with a self-contained .gitignore file. I'll work on a PR for this shortly.

[w0rd-driven]

Yeah it looks like commit d2b6848 introduced the change. I prefer the original approach and as I can't determine when you'd want to recreate the directory like it's doing now. I know the json file changed between Swagger versions but that should be the only thing generation touches to my knowledge. If deleting that file before writing to it is a problem then we can just delete that one file explicitly, not the entire directory.

[mikylucky]

Is this the issue causing my path "/api-docs" not found?

[w0rd-driven]

It's possible but probably not. In your config/swaggervel.php there's a line: 'doc-dir' => storage_path() . '/docs',. This points to the storage/docs/ directory which is being overwritten on every generate.

If you're getting path not found, it likely points to Jlapp\Swaggervel\SwaggervelServiceProvider::class, not being before the section labelled Application Service Providers... in your config/app.php providers list. https://github.com/slampenny/Swaggervel#installation says to place this above App\Providers\RouteServiceProvider::class,.

[mikylucky]

@w0rd-driven actually my Jlapp\Swaggervel\SwaggervelServiceProvider::class is placed before all the other providers

[w0rd-driven]

I would ask what version you're using but that's really hard to track. There was a recent change that adds 'api-docs-route' => 'api/docs', to the config. If you have the code for that revision but haven't updated the config that could be a problem. That route should also be 'api-docs' to match the current convention.

What is the output of php artisan route:list?

[mikylucky]

I haven't that string in my config and artisan gives me error

[Error Exception]
Undfined index: token

[w0rd-driven]

Hrm I've never seen that before. When's the last time you updated this package? You may not need that section in your config file if you haven't updated in awhile. If you've updated recently then chances are you'll need that. route:list should be giving you a list of valid routes. It's probably not necessary for Laravel to work but the fact that it isn't returning anything may be pointing to the problem. Unfortunately that error is extremely generic and doesn't really point to what the problem could be.

[mikylucky]

I'm an "update maniac" :D So i'm sure I have the last version of swaggervel.

I've just tried putting 'api-docs-route' => 'api/docs' in my config file and something happens: I can access the docs to the new path, but all the style is completely missing.

Could be an incomplete update?

[w0rd-driven]

I personally changed mine back to api-docs. That was a breaking change introduced in the patch that should be reverted.

I also had to update resources/views/vendor/swaggervel/index.blade.php. The patch introduced many files as /vendor... I had to strip out the /. The front slash only works if your laravel project is at the top of the docroot. This project is a subdirectory so it had to be stripped.

I found that using {{ url('vendor/swaggervel/images/favicon-32x32.png') }} is probably the more preferred way to handle that. It resolves to the hardcoded location this should exist on the server, rather than try to use relative pathing madness that starts to get squirrelly.

[mikylucky]

Things are getting strange!

If i replace api/docs with api-docs, nothing changes! Docs are still in api/docs

And nothing changes if I remove the / in the index.blade.php

[w0rd-driven]

Hrm I'm really stumped. If you know how to inspect the vendor code, I would try to make sure I was on the latest version of the package. You may just want to delete your config, re-run the publish command and look at the diff of what's changed in git. There may be more config dependencies.

You could also try to use "api/docs" as before and open Chrome to look for any 404 errors. If you get no CSS applied giving you at least the top portion of the Swagger UI then it can't find the assets in the public folder. If you're getting that but no API generated then something is bombing when it's trying to generate your docs. Have you tried going to the doc-route route and made sure it generates the JSON? I may be asking basic questions but when I troubleshoot I like to eliminate even the most mundane possibilities to focus on what's left.