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

Conversation

Projects
None yet
3 participants
@Simperfit
Member

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

$className = $type->getClassName();
if ($this->resourceClassResolver->isResourceClass($className)) {
return ['$ref' => sprintf('#/definitions/%s', $this->resourceMetadataFactory->create($className)->getShortName())];
}

This comment has been minimized.

@dunglas

dunglas Jul 3, 2016

Member

Is it ok to ignore classes that are not dates nor resources?

@dunglas

dunglas Jul 3, 2016

Member

Is it ok to ignore classes that are not dates nor resources?

This comment has been minimized.

@Simperfit

Simperfit Jul 4, 2016

Member

I guess yes because they are not definitions

@Simperfit

Simperfit Jul 4, 2016

Member

I guess yes because they are not definitions

@dunglas

This comment has been minimized.

Show comment
Hide comment
@dunglas

dunglas Jul 3, 2016

Member

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.

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

This comment has been minimized.

Show comment
Hide comment
@Simperfit

Simperfit Jul 4, 2016

Member

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

Member

Simperfit commented Jul 4, 2016

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

@dunglas

This comment has been minimized.

Show comment
Hide comment
@dunglas

dunglas Jul 4, 2016

Member

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.

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.

@theofidry

This comment has been minimized.

Show comment
Hide comment
@theofidry

theofidry Jul 4, 2016

Member

@Simperfit couldn't check it in details, but I left some notes here and there and you have some Scrutinizer warnings :)

Member

theofidry commented Jul 4, 2016

@Simperfit couldn't check it in details, but I left some notes here and there and you have some Scrutinizer warnings :)

try {
$resourceClassIri = $this->iriConverter->getIriFromResourceClass($resourceClass);
} catch (InvalidArgumentException $e) {
$resourceClassIri = '/nopaths';

This comment has been minimized.

@dunglas

dunglas Jul 4, 2016

Member

What is the reason of this?

@dunglas

dunglas Jul 4, 2016

Member

What is the reason of this?

This comment has been minimized.

@Simperfit

Simperfit Jul 4, 2016

Member

Because in the tests NoCollectionDummy does throw an error in here.

@Simperfit

Simperfit Jul 4, 2016

Member

Because in the tests NoCollectionDummy does throw an error in here.

@@ -22,10 +22,13 @@ before_install:
- if [ "$TRAVIS_PHP_VERSION" != "hhvm" ]; then phpenv config-rm xdebug.ini; fi;
- phpunit --self-update
- if [ "$SYMFONY_VERSION" != "" ]; then composer require "symfony/symfony:${SYMFONY_VERSION}" --no-update; fi;
- npm install -g swagger-cli

This comment has been minimized.

@theofidry

theofidry Jul 4, 2016

Member

outch, IMO it would be better to have it in a packages.json and shrinkwrap it. node_modules could then be cached like it is for composer

@theofidry

theofidry Jul 4, 2016

Member

outch, IMO it would be better to have it in a packages.json and shrinkwrap it. node_modules could then be cached like it is for composer

This comment has been minimized.

@dunglas

dunglas Jul 4, 2016

Member

IMO it's better as is. Having a packages.json in the repository (that doesn't use any NPM dependency) has no sense and it's good to test the Swagger support with the latest available version of swagger-cli (we also install the last version of composer for instance).

@dunglas

dunglas Jul 4, 2016

Member

IMO it's better as is. Having a packages.json in the repository (that doesn't use any NPM dependency) has no sense and it's good to test the Swagger support with the latest available version of swagger-cli (we also install the last version of composer for instance).

This comment has been minimized.

@theofidry

theofidry Jul 4, 2016

Member

Having a packages.json in the repository (that doesn't use any NPM dependency) has no sense

Well, with this we are. If we don't add it it's a hidden project dependency. Not required unless you are developing on this bit, but hidden still. Having a packages.json does not force you to do a npm install when you want to get started with the project, but at least it avoids people to have to look at Travis to figure out that they need swagger-cli.

it's good to test the Swagger support with the latest available version of swagger-cli

In that case yeah we can drop the npm-shrinkwrap.json thing, which makes it even easier as unlike composer, shrinkwrap depends on the local node version installed

@theofidry

theofidry Jul 4, 2016

Member

Having a packages.json in the repository (that doesn't use any NPM dependency) has no sense

Well, with this we are. If we don't add it it's a hidden project dependency. Not required unless you are developing on this bit, but hidden still. Having a packages.json does not force you to do a npm install when you want to get started with the project, but at least it avoids people to have to look at Travis to figure out that they need swagger-cli.

it's good to test the Swagger support with the latest available version of swagger-cli

In that case yeah we can drop the npm-shrinkwrap.json thing, which makes it even easier as unlike composer, shrinkwrap depends on the local node version installed

This comment has been minimized.

@dunglas

dunglas Jul 4, 2016

Member

They don't need it to develop. It's just an extra check we do in the CI to be sure that the output of the Swagger generator is correct.
If we used a go validator (goswagger is able to validate Swagger files), we would not have versioned a go setup in the repo just to use this program.

@dunglas

dunglas Jul 4, 2016

Member

They don't need it to develop. It's just an extra check we do in the CI to be sure that the output of the Swagger generator is correct.
If we used a go validator (goswagger is able to validate Swagger files), we would not have versioned a go setup in the repo just to use this program.

This comment has been minimized.

@theofidry

theofidry Jul 4, 2016

Member

fair enough

@theofidry

theofidry Jul 4, 2016

Member

fair enough

@dunglas

This comment has been minimized.

Show comment
Hide comment
@dunglas

dunglas Jul 4, 2016

Member

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!

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!

*
* @throws Exception
*
* @return array | stdClass

This comment has been minimized.

@theofidry

theofidry Jul 4, 2016

Member

IMO everything except the Gets an operation by its method name. can be removed. As the context is not meant to be reused, indicating that an exception is thrown is useless

@theofidry

theofidry Jul 4, 2016

Member

IMO everything except the Gets an operation by its method name. can be removed. As the context is not meant to be reused, indicating that an exception is thrown is useless

This comment has been minimized.

@theofidry

theofidry Jul 4, 2016

Member

you also have a return typehint mismatch

@theofidry

theofidry Jul 4, 2016

Member

you also have a return typehint mismatch

This comment has been minimized.

@Simperfit

Simperfit Jul 5, 2016

Member

done

@Simperfit

Simperfit Jul 5, 2016

Member

done

@dunglas

This comment has been minimized.

Show comment
Hide comment
@dunglas

dunglas Jul 4, 2016

Member

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

Member

dunglas commented Jul 4, 2016

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

@Simperfit

This comment has been minimized.

Show comment
Hide comment
@Simperfit

Simperfit Jul 5, 2016

Member

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

Member

Simperfit commented Jul 5, 2016

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

@dunglas

This comment has been minimized.

Show comment
Hide comment
@dunglas

dunglas Jul 6, 2016

Member

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

Member

dunglas commented Jul 6, 2016

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

Simperfit added some commits Jul 3, 2016

@Simperfit

This comment has been minimized.

Show comment
Hide comment
@Simperfit

Simperfit Jul 6, 2016

Member

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

Member

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

This comment has been minimized.

Show comment
Hide comment
@dunglas

dunglas Jul 6, 2016

Member

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

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

4 checks passed

Scrutinizer 18 new issues, 14 updated code elements
Details
StyleCI The StyleCI analysis has passed
Details
continuous-integration/appveyor/pr AppVeyor build succeeded
Details
continuous-integration/travis-ci/pr The Travis CI build passed
Details
@dunglas

This comment has been minimized.

Show comment
Hide comment
@dunglas

dunglas Jul 7, 2016

Member

Thank you @Simperfit

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