Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

feat: swagger v2 #591

Merged
merged 3 commits into from Jul 7, 2016
Merged

Conversation

Simperfit
Copy link
Contributor

@Simperfit Simperfit commented Jul 3, 2016

Q A
Bug fix? no
New feature? yes
BC breaks? yes if we remove nelmio
Deprecations? no
Tests pass? yes
Fixed tickets #538
License MIT
Doc PR todo

Since NelmioApiDocBundle is not going to update to swagger v2, we will do it in api-platform.

This is WIP :

  • Add tests (unit / behat) [ see https://travis-ci.org/api-platform/core/jobs/142226685#L4610]
  • Refactor, delete maximum of dupplication
  • look at scrutinizer

I have been doing that today, tested with SwaggerUI by changing the format of hydra / swagger

*
* @param XmlFileLoader $loader
*/
private function enableJsonLd(XmlFileLoader $loader)
{
$loader->load('jsonld.xml');
$loader->load('hydra.xml');
$loader->load('swagger.xml');
Copy link
Member

@dunglas dunglas Jul 3, 2016

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@dunglas
Copy link
Member

dunglas commented Jul 3, 2016

First of all, thanks for working on this @Simperfit. It's very much appreciated.

Unless JSON-LD, HAL or JSON API, Swagger is just an API documentation format. Not all resources exposed by the API will be available in the "Swagger". There will be only one new URL returning the Swagger doc.

Basically, you can keep your Swagger\ApiDocumentationBuilder and add a new Swagger action (mapped to a /swagger path for instance) and you're all done. When someone will want to use Swagger UI, it will query this URL. Then Swagger UI will send JSON-LD requests to the API.

@Simperfit
Copy link
Contributor Author

Simperfit commented Jul 4, 2016

@dunglas Comments taken in account. I've added a console command that dumps the documentation

*
* @author Amrouche Hamza <hamza.simperfit@gmail.com>
*/
class SwaggerCommand extends Command
Copy link
Member

@dunglas dunglas Jul 4, 2016

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Can you make this class final?

@dunglas
Copy link
Member

dunglas commented Jul 4, 2016

When you'll write tests, you can use https://hub.docker.com/r/swaggerapi/swagger-validator/ to validate the generated Swagger file of the test app in Travis.

{
/** @var InitializedContextEnvironment $environment */
$environment = $scope->getEnvironment();
$this->restContext = $environment->getContext('Sanpi\Behatch\Context\RestContext');
Copy link
Contributor

@theofidry theofidry Jul 4, 2016

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Sanpi\Behatch\Context\RestContext::class?

@@ -60,6 +60,7 @@ public function load($data, $type = null)

$routeCollection->addCollection($this->fileLoader->load('jsonld.xml'));
$routeCollection->addCollection($this->fileLoader->load('hydra.xml'));
$routeCollection->addCollection($this->fileLoader->load('swagger.xml'));
Copy link
Member

@dunglas dunglas Jul 4, 2016

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Should be loaded only if the config flag is set to true.

@dunglas
Copy link
Member

dunglas commented Jul 4, 2016

I left some minor comments but it looks good to me. What do you think @api-platform/core-team I want it in the first beta too!

$propertyInfos = null;
foreach ($properties as $classPropertyName => $property) {
if ($classPropertyName === $propertyName) {
$propertyInfos = $property;
Copy link
Contributor

@theofidry theofidry Jul 4, 2016

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

do we have to iterate over all the properties? Can't we return as soon as we got one?

@dunglas
Copy link
Member

dunglas commented Jul 4, 2016

Can you also add a unit test for the Swagger generator?

@Simperfit
Copy link
Contributor Author

Simperfit commented Jul 5, 2016

@dunglas I asserted the Json, what do I test ? Like in behat ?

@dunglas
Copy link
Member

dunglas commented Jul 6, 2016

@Simperfit a PHPUnit test on the class itself would be the best. Can you resolve conflicts too?

@Simperfit
Copy link
Contributor Author

Simperfit commented Jul 6, 2016

@dunglas I've added one on the console,
Do I have to add one on the ApiDocumentationBuilder ?
I have rebased

@dunglas
Copy link
Member

dunglas commented Jul 6, 2016

On the builder. We try to have unit tests for every new classes.

@dunglas dunglas merged commit dc227ec into api-platform:master Jul 7, 2016
@dunglas
Copy link
Member

dunglas commented Jul 7, 2016

Thank you @Simperfit

magarzon pushed a commit to magarzon/core that referenced this pull request Feb 12, 2017
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

None yet

3 participants