Improved architecture with many new features and improved stability. #66

Merged
merged 5 commits into from Apr 3, 2013

Conversation

Projects
None yet
2 participants
@bfanger
Collaborator

bfanger commented Mar 25, 2013

  • New architecture
    • Split Swagger class into Swagger & Parser.
      Parser focuses on extracting swagger comments and converting them into a valid Resource or Model objects.
      Swagger provides the public api and crawls the project folder.
    • Add Logger, instead of crashing with an Exception, Swagger now reports the error and skips entries that are invalid or incomplete.
    • Split the Annotation->toArray into:
      • __contruct() import the data extracted by doctrine. (Parser might augement this data)
      • validate() tries to create a optimal valid data-structure and returns false if the annotation can't be used.
      • jsonSerialize() serializing the Annotation to the format expected by swagger-ui.
    • The Swagger->repository now consists of a more predictable object-tree instead of errror prone array struct.
  • User features
    • Running bin/swagger without arguments now shows the help.
    • All encapsulation annotations are now optional, and might be deprecated in the future.
      @api(@operations(@operation(), @operation())) is the same as @api(@operation(), @operation())
    • Show human readable hints/notices instead of "undefined index xxxx" notices.
    • Augment Swagger comments with available data from class/property/method or remaining data in the doc-comment.
      • Example @model() used the classname as id
    • An @api can be nested inside a @resource and @property can be nested inside a @model.
Improved architecture with many new features and improved stability.
* New architecture
  * Split Swagger class into Swagger & Parser.
    Parser focuses on extracting swagger comments and converting them into a valid Resource or Model objects.
    Swagger provides the public api and crawls the project folder.

  * Add Logger, instead of crashing with an Exception, Swagger now reports the error and skips entries that are invalid or incomplete.

  * Split the Annotation->toArray into:
    * __contruct() import the data extracted by doctrine. (Parser might augement this data)
    * validate() tries to create a optimal valid data-structure and returns false if the annotation can't be used.
    * jsonSerialize() serializing the Annotation to the format expected by swagger-ui.

  * The Swagger->repository now consists of a more predictable object-tree instead of errror prone array struct.

* User features
  * Running bin/swagger without arguments now shows the help.

  * All encapsulation annotations are now optional, and might be deprecated in the future.
	@Api(@Operations(@Operation(), @Operation())) is the same as @Api(@Operation(), @Operation())

  * Show human readable hints/notices instead of "undefined index xxxx" notices.

  * Augment Swagger comments with available data from class/property/method or remaining data in the doc-comment.
    * Example @Model() used the classname as id

  * An @Api can be nested inside a @Resource and @Property can be nested inside a @Model.
@bfanger

This comment has been minimized.

Show comment Hide comment
@bfanger

bfanger Mar 25, 2013

Collaborator

The master branch incorporated additional patches since i started with re-structureing the swagger parser. I'll try to merge those changes this afternoon, but i would like some get some feedback on the current state.

It's a very big commit, so I expect to do some additional patching ;)

Collaborator

bfanger commented Mar 25, 2013

The master branch incorporated additional patches since i started with re-structureing the swagger parser. I'll try to merge those changes this afternoon, but i would like some get some feedback on the current state.

It's a very big commit, so I expect to do some additional patching ;)

@zircote

This comment has been minimized.

Show comment Hide comment
@zircote

zircote Mar 26, 2013

Owner

@bfanger while I have not had time to go through it all and run tests it looks great so far. I will carve some time this week to review it thoroughly.

I would like to thank you for the time you have in this it looks to be a nice direction and it is appreciated.

Owner

zircote commented Mar 26, 2013

@bfanger while I have not had time to go through it all and run tests it looks great so far. I will carve some time this week to review it thoroughly.

I would like to thank you for the time you have in this it looks to be a nice direction and it is appreciated.

@zircote

This comment has been minimized.

Show comment Hide comment
@zircote

zircote Apr 2, 2013

Owner

Let me know when you think this is stable and ready for a final review.

Also could you outline any excepted/known BC breaks that this may have introduced?

/cc @bfanger

Owner

zircote commented Apr 2, 2013

Let me know when you think this is stable and ready for a final review.

Also could you outline any excepted/known BC breaks that this may have introduced?

/cc @bfanger

@bfanger

This comment has been minimized.

Show comment Hide comment
@bfanger

bfanger Apr 2, 2013

Collaborator

It's ready. It worked as expected on the code I threw at it.
Let me know if you find any regressions.

Collaborator

bfanger commented Apr 2, 2013

It's ready. It worked as expected on the code I threw at it.
Let me know if you find any regressions.

@bfanger

This comment has been minimized.

Show comment Hide comment
@bfanger

bfanger Apr 2, 2013

Collaborator

I tried to be as compatible as possible. The only deliberate breakage is in the Property type.
Which has become case-sensitive. (But shows a hint when "array" is used instead of "Array"
This guides the users to use the same notation throughout their documentation

Collaborator

bfanger commented Apr 2, 2013

I tried to be as compatible as possible. The only deliberate breakage is in the Property type.
Which has become case-sensitive. (But shows a hint when "array" is used instead of "Array"
This guides the users to use the same notation throughout their documentation

zircote added a commit that referenced this pull request Apr 3, 2013

Merge pull request #66 from bfanger/nextgen
Improved architecture with many new features and improved stability.

@zircote zircote merged commit 4c12ceb into zircote:master Apr 3, 2013

1 check passed

default The Travis build passed
Details
@zircote

This comment has been minimized.

Show comment Hide comment
@zircote

zircote Apr 3, 2013

Owner

Nice improvements, thank you.

Owner

zircote commented Apr 3, 2013

Nice improvements, thank you.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment