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

API status annotation #122

Closed
ntatsumi opened this Issue Jul 13, 2015 · 8 comments

Comments

Projects
None yet
2 participants
@ntatsumi

ntatsumi commented Jul 13, 2015

I have a need to indicate the status of API class and API methods that informs the consumers whether they are in "public", "private", "deprecated", or "beta" mode. I'd like to create a PR that introduces 'ApiStatus' annotation with the following signature:

Level: class, method

Property: public, deprecated, beta (all defaults to false)

Let me know what you think! Thanks.

@fabiomaffioletti

This comment has been minimized.

Show comment
Hide comment
@fabiomaffioletti

fabiomaffioletti Aug 5, 2015

Owner

I think you are mixing different concepts here: public / private belong to the "visibility" world. beta / deprecated and related stuff like alpha, RC, GA belong to the "development stage". Plus I would not add another annotation because people is already saying that there are too many annotation that make their code dirty.

So here is what I would do.

  1. add two properties to the @Api and @ApiMethod annotations, named "visibility" and "stage"
  2. visibility is an enum ApiVisilibity with values PRIVATE, PUBLIC. Defaults to empty, meaning that it's not mandatory for the user to fill the property with a value. In case it's empty then it's not shown on the UI.
  3. stage is an enum ApiStage with values PRE-ALPHA, ALPHA, BETA, RC, GA, DEPRECATED. Defaults to empty, meaning that it's not mandatory for the user to fill the property with a value. In case it's empty then it's not shown on the UI.
  4. methods inherit visibility and stage from types.
  5. if both method and type specify the visibility, then the type value will override the method one: if the type is PRIVATE, the method cannot be PUBLIC and vice versa
  6. the same goes for the stage

Let me know what you think and if you want to modify your pull request. Thanks.

Owner

fabiomaffioletti commented Aug 5, 2015

I think you are mixing different concepts here: public / private belong to the "visibility" world. beta / deprecated and related stuff like alpha, RC, GA belong to the "development stage". Plus I would not add another annotation because people is already saying that there are too many annotation that make their code dirty.

So here is what I would do.

  1. add two properties to the @Api and @ApiMethod annotations, named "visibility" and "stage"
  2. visibility is an enum ApiVisilibity with values PRIVATE, PUBLIC. Defaults to empty, meaning that it's not mandatory for the user to fill the property with a value. In case it's empty then it's not shown on the UI.
  3. stage is an enum ApiStage with values PRE-ALPHA, ALPHA, BETA, RC, GA, DEPRECATED. Defaults to empty, meaning that it's not mandatory for the user to fill the property with a value. In case it's empty then it's not shown on the UI.
  4. methods inherit visibility and stage from types.
  5. if both method and type specify the visibility, then the type value will override the method one: if the type is PRIVATE, the method cannot be PUBLIC and vice versa
  6. the same goes for the stage

Let me know what you think and if you want to modify your pull request. Thanks.

@fabiomaffioletti fabiomaffioletti modified the milestone: 1.1.17 Aug 5, 2015

@ntatsumi

This comment has been minimized.

Show comment
Hide comment
@ntatsumi

ntatsumi Aug 5, 2015

You bring up some good points. I'll create another PR based on the design considerations you listed.

ntatsumi commented Aug 5, 2015

You bring up some good points. I'll create another PR based on the design considerations you listed.

@ntatsumi

This comment has been minimized.

Show comment
Hide comment
@ntatsumi

ntatsumi Aug 10, 2015

@fabiomaffioletti I'd like to add visibility and stage to ApiObject as well. Let me know if I can add it to this PR or I should create a separate issue. Thanks.

ntatsumi commented Aug 10, 2015

@fabiomaffioletti I'd like to add visibility and stage to ApiObject as well. Let me know if I can add it to this PR or I should create a separate issue. Thanks.

@fabiomaffioletti

This comment has been minimized.

Show comment
Hide comment
@fabiomaffioletti

fabiomaffioletti Aug 11, 2015

Owner

The task is ok, but I suggest you to wait a bit: I made a bit of refactoring in the ISSUE-127 branch so it's better to wait for me to merge it to master before implementing this. I also had to take your work and manually integrate it in the branch. I'll let you know, is it ok for you?

Owner

fabiomaffioletti commented Aug 11, 2015

The task is ok, but I suggest you to wait a bit: I made a bit of refactoring in the ISSUE-127 branch so it's better to wait for me to merge it to master before implementing this. I also had to take your work and manually integrate it in the branch. I'll let you know, is it ok for you?

@ntatsumi

This comment has been minimized.

Show comment
Hide comment
@ntatsumi

ntatsumi Aug 11, 2015

Sure. That works.

ntatsumi commented Aug 11, 2015

Sure. That works.

@fabiomaffioletti

This comment has been minimized.

Show comment
Hide comment
@fabiomaffioletti

fabiomaffioletti Aug 11, 2015

Owner

Just merged branch ISSUE-127 to master. Be sure to start from this before adding visibility and stage to @ApiObject.

Owner

fabiomaffioletti commented Aug 11, 2015

Just merged branch ISSUE-127 to master. Be sure to start from this before adding visibility and stage to @ApiObject.

@fabiomaffioletti

This comment has been minimized.

Show comment
Hide comment
@fabiomaffioletti

fabiomaffioletti Aug 13, 2015

Owner

@ntatsumi any news on this?

Owner

fabiomaffioletti commented Aug 13, 2015

@ntatsumi any news on this?

@ntatsumi

This comment has been minimized.

Show comment
Hide comment
@ntatsumi

ntatsumi Aug 13, 2015

@fabiomaffioletti I'll work on it tonight.

ntatsumi commented Aug 13, 2015

@fabiomaffioletti I'll work on it tonight.

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