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

API status annotation #122

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

API status annotation #122

ntatsumi opened this issue Jul 13, 2015 · 8 comments
Milestone

Comments

@ntatsumi
Copy link

@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
Copy link
Owner

@fabiomaffioletti 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
Copy link
Author

@ntatsumi ntatsumi commented Aug 5, 2015

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

@ntatsumi
Copy link
Author

@ntatsumi 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
Copy link
Owner

@fabiomaffioletti 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
Copy link
Author

@ntatsumi ntatsumi commented Aug 11, 2015

Sure. That works.

@fabiomaffioletti
Copy link
Owner

@fabiomaffioletti 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
Copy link
Owner

@fabiomaffioletti fabiomaffioletti commented Aug 13, 2015

@ntatsumi any news on this?

@ntatsumi
Copy link
Author

@ntatsumi 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
Projects
None yet
Linked pull requests

Successfully merging a pull request may close this issue.

None yet
2 participants
You can’t perform that action at this time.