{"action":"created","issue":{"url":"https://api.github.com/repos/stoicflame/enunciate/issues/306","repository_url":"https://api.github.com/repos/stoicflame/enunciate","labels_url":"https://api.github.com/repos/stoicflame/enunciate/issues/306/labels{/name}","comments_url":"https://api.github.com/repos/stoicflame/enunciate/issues/306/comments","events_url":"https://api.github.com/repos/stoicflame/enunciate/issues/306/events","html_url":"https://github.com/stoicflame/enunciate/issues/306","id":132280942,"number":306,"title":"Question: Why Annotations and not custom Javadoc-Tags?","user":{"login":"cheppsn","id":5145827,"avatar_url":"https://avatars.githubusercontent.com/u/5145827?v=3","gravatar_id":"","url":"https://api.github.com/users/cheppsn","html_url":"https://github.com/cheppsn","followers_url":"https://api.github.com/users/cheppsn/followers","following_url":"https://api.github.com/users/cheppsn/following{/other_user}","gists_url":"https://api.github.com/users/cheppsn/gists{/gist_id}","starred_url":"https://api.github.com/users/cheppsn/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/cheppsn/subscriptions","organizations_url":"https://api.github.com/users/cheppsn/orgs","repos_url":"https://api.github.com/users/cheppsn/repos","events_url":"https://api.github.com/users/cheppsn/events{/privacy}","received_events_url":"https://api.github.com/users/cheppsn/received_events","type":"User","site_admin":false},"labels":[{"url":"https://api.github.com/repos/stoicflame/enunciate/labels/enhancement","name":"enhancement","color":"207de5"}],"state":"closed","locked":false,"assignee":null,"milestone":{"url":"https://api.github.com/repos/stoicflame/enunciate/milestones/10","html_url":"https://github.com/stoicflame/enunciate/milestones/2.3.0","labels_url":"https://api.github.com/repos/stoicflame/enunciate/milestones/10/labels","id":1507423,"number":10,"title":"2.3.0","description":"","creator":{"login":"stoicflame","id":145838,"avatar_url":"https://avatars.githubusercontent.com/u/145838?v=3","gravatar_id":"","url":"https://api.github.com/users/stoicflame","html_url":"https://github.com/stoicflame","followers_url":"https://api.github.com/users/stoicflame/followers","following_url":"https://api.github.com/users/stoicflame/following{/other_user}","gists_url":"https://api.github.com/users/stoicflame/gists{/gist_id}","starred_url":"https://api.github.com/users/stoicflame/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/stoicflame/subscriptions","organizations_url":"https://api.github.com/users/stoicflame/orgs","repos_url":"https://api.github.com/users/stoicflame/repos","events_url":"https://api.github.com/users/stoicflame/events{/privacy}","received_events_url":"https://api.github.com/users/stoicflame/received_events","type":"User","site_admin":false},"open_issues":26,"closed_issues":55,"state":"open","created_at":"2016-01-14T18:04:11Z","updated_at":"2016-03-15T15:47:38Z","due_on":null,"closed_at":null},"comments":3,"created_at":"2016-02-08T22:56:44Z","updated_at":"2016-03-15T15:47:38Z","closed_at":"2016-03-15T15:47:38Z","body":"Just a curious question (I read in the FAQ that an issue seems to be appropriate for this):\r\n\r\nEnunciate solves the problem of \"missing information\" with custom annotations that can be added to the API code. We are currently in the process of evaluating Enunciate as an alternative to Spring-Fox for Swagger, which we want to dump, because no one can see the relevant code anymore due to way too many annotations.\r\n\r\nEnunciate may help us solving many of those problems, especially with respect to method documentation, which can now be done with Javadoc instead of using an annotation. However, I wonder why the Enunciate-extensions were realized as custom annotations and not as custom Javadoc tags? If e.g. response-codes or labels were Javadoc-Tags, they would not lead to \"stacks of annotations\" above a method declaration and could be folded away easily in most IDEs.\r\n\r\nI understand that annotations will end up in Javac's AST and are thus easy to process. But I've just had the experience with Springfox, that annotations which are not relevant for the execution lead both to confusion and irritation. If they were contained in the comment, it would be instantly clear, that they have only documentational value."},"comment":{"url":"https://api.github.com/repos/stoicflame/enunciate/issues/comments/196889694","html_url":"https://github.com/stoicflame/enunciate/issues/306#issuecomment-196889694","issue_url":"https://api.github.com/repos/stoicflame/enunciate/issues/306","id":196889694,"user":{"login":"stoicflame","id":145838,"avatar_url":"https://avatars.githubusercontent.com/u/145838?v=3","gravatar_id":"","url":"https://api.github.com/users/stoicflame","html_url":"https://github.com/stoicflame","followers_url":"https://api.github.com/users/stoicflame/followers","following_url":"https://api.github.com/users/stoicflame/following{/other_user}","gists_url":"https://api.github.com/users/stoicflame/gists{/gist_id}","starred_url":"https://api.github.com/users/stoicflame/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/stoicflame/subscriptions","organizations_url":"https://api.github.com/users/stoicflame/orgs","repos_url":"https://api.github.com/users/stoicflame/repos","events_url":"https://api.github.com/users/stoicflame/events{/privacy}","received_events_url":"https://api.github.com/users/stoicflame/received_events","type":"User","site_admin":false},"created_at":"2016-03-15T15:47:38Z","updated_at":"2016-03-15T15:47:38Z","body":"Fixed at a50fe0f.\r\n\r\nDocumentation at https://github.com/stoicflame/enunciate/wiki/Enunciate-Specific-Annotations updated."}}