{"action":"created","issue":{"url":"https://api.github.com/repos/Surnet/swagger-jsdoc/issues/65","repository_url":"https://api.github.com/repos/Surnet/swagger-jsdoc","labels_url":"https://api.github.com/repos/Surnet/swagger-jsdoc/issues/65/labels{/name}","comments_url":"https://api.github.com/repos/Surnet/swagger-jsdoc/issues/65/comments","events_url":"https://api.github.com/repos/Surnet/swagger-jsdoc/issues/65/events","html_url":"https://github.com/Surnet/swagger-jsdoc/issues/65","id":215201966,"node_id":"MDU6SXNzdWUyMTUyMDE5NjY=","number":65,"title":"[Maintainer] Open API spec","user":{"login":"kalinchernev","id":1923476,"node_id":"MDQ6VXNlcjE5MjM0NzY=","avatar_url":"https://avatars3.githubusercontent.com/u/1923476?v=4","gravatar_id":"","url":"https://api.github.com/users/kalinchernev","html_url":"https://github.com/kalinchernev","followers_url":"https://api.github.com/users/kalinchernev/followers","following_url":"https://api.github.com/users/kalinchernev/following{/other_user}","gists_url":"https://api.github.com/users/kalinchernev/gists{/gist_id}","starred_url":"https://api.github.com/users/kalinchernev/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/kalinchernev/subscriptions","organizations_url":"https://api.github.com/users/kalinchernev/orgs","repos_url":"https://api.github.com/users/kalinchernev/repos","events_url":"https://api.github.com/users/kalinchernev/events{/privacy}","received_events_url":"https://api.github.com/users/kalinchernev/received_events","type":"User","site_admin":false},"labels":[],"state":"open","locked":false,"assignee":{"login":"drGrove","id":1441230,"node_id":"MDQ6VXNlcjE0NDEyMzA=","avatar_url":"https://avatars0.githubusercontent.com/u/1441230?v=4","gravatar_id":"","url":"https://api.github.com/users/drGrove","html_url":"https://github.com/drGrove","followers_url":"https://api.github.com/users/drGrove/followers","following_url":"https://api.github.com/users/drGrove/following{/other_user}","gists_url":"https://api.github.com/users/drGrove/gists{/gist_id}","starred_url":"https://api.github.com/users/drGrove/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/drGrove/subscriptions","organizations_url":"https://api.github.com/users/drGrove/orgs","repos_url":"https://api.github.com/users/drGrove/repos","events_url":"https://api.github.com/users/drGrove/events{/privacy}","received_events_url":"https://api.github.com/users/drGrove/received_events","type":"User","site_admin":false},"assignees":[{"login":"drGrove","id":1441230,"node_id":"MDQ6VXNlcjE0NDEyMzA=","avatar_url":"https://avatars0.githubusercontent.com/u/1441230?v=4","gravatar_id":"","url":"https://api.github.com/users/drGrove","html_url":"https://github.com/drGrove","followers_url":"https://api.github.com/users/drGrove/followers","following_url":"https://api.github.com/users/drGrove/following{/other_user}","gists_url":"https://api.github.com/users/drGrove/gists{/gist_id}","starred_url":"https://api.github.com/users/drGrove/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/drGrove/subscriptions","organizations_url":"https://api.github.com/users/drGrove/orgs","repos_url":"https://api.github.com/users/drGrove/repos","events_url":"https://api.github.com/users/drGrove/events{/privacy}","received_events_url":"https://api.github.com/users/drGrove/received_events","type":"User","site_admin":false},{"login":"kalinchernev","id":1923476,"node_id":"MDQ6VXNlcjE5MjM0NzY=","avatar_url":"https://avatars3.githubusercontent.com/u/1923476?v=4","gravatar_id":"","url":"https://api.github.com/users/kalinchernev","html_url":"https://github.com/kalinchernev","followers_url":"https://api.github.com/users/kalinchernev/followers","following_url":"https://api.github.com/users/kalinchernev/following{/other_user}","gists_url":"https://api.github.com/users/kalinchernev/gists{/gist_id}","starred_url":"https://api.github.com/users/kalinchernev/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/kalinchernev/subscriptions","organizations_url":"https://api.github.com/users/kalinchernev/orgs","repos_url":"https://api.github.com/users/kalinchernev/repos","events_url":"https://api.github.com/users/kalinchernev/events{/privacy}","received_events_url":"https://api.github.com/users/kalinchernev/received_events","type":"User","site_admin":false},{"login":"chdanielmueller","id":4051999,"node_id":"MDQ6VXNlcjQwNTE5OTk=","avatar_url":"https://avatars2.githubusercontent.com/u/4051999?v=4","gravatar_id":"","url":"https://api.github.com/users/chdanielmueller","html_url":"https://github.com/chdanielmueller","followers_url":"https://api.github.com/users/chdanielmueller/followers","following_url":"https://api.github.com/users/chdanielmueller/following{/other_user}","gists_url":"https://api.github.com/users/chdanielmueller/gists{/gist_id}","starred_url":"https://api.github.com/users/chdanielmueller/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/chdanielmueller/subscriptions","organizations_url":"https://api.github.com/users/chdanielmueller/orgs","repos_url":"https://api.github.com/users/chdanielmueller/repos","events_url":"https://api.github.com/users/chdanielmueller/events{/privacy}","received_events_url":"https://api.github.com/users/chdanielmueller/received_events","type":"User","site_admin":false}],"milestone":null,"comments":13,"created_at":"2017-03-18T15:40:43Z","updated_at":"2018-07-10T20:14:00Z","closed_at":null,"author_association":"COLLABORATOR","body":"I'll use the opportunity and the recent maintainers' activity to rise another high-level question I think will be good to start considering: the upcoming update in the swagger specification which becomes [open api spec](https://www.openapis.org/specification/repo).\r\n\r\nThe situation we have at the moment as I see it is as following.\r\n\r\n## Community ##\r\nHigh-level observations:\r\n- [v3 rc was released recently](https://github.com/OAI/OpenAPI-Specification/releases/tag/3.0.0-rc0), which probably means it's a good time to open the discussion\r\n- [research efforts on tooling migration](http://apievangelist.com/2017/03/16/what-will-it-take-to-evolve-openapi-tooling-to-version-30/) also has started by a prominent figure in the community\r\n- I think that with good strategy, swagger-jsdoc could target a good positioning in the documentation segment of the [open api spec toolchain](http://openapi.toolbox.apievangelist.com/). Could also be in a general tooling of node.js, though I think that the momentum of the last year could be used as an advantage to seek a concrete positioning and purpose.\r\n\r\nAlthough I'm not having the opportunity to be a full-time API architect or developer, the little time I manage to get from side projects and prototyping tasks, I already feel that swagger-jsdoc could be a useful tool when documentation in code can be reused as documentation out of code.\r\n\r\nFor example, here are 2 experiments I've been having recently:\r\n- [Agile documentation for your API-driven project](https://restful.io/agile-documentation-for-your-api-driven-project-based-on-open-api-standards-11e54d4326bb#.7hoklyslr)\r\n- [Prototyping your API project with the Open API specification and node.js tools](https://medium.com/@kalin.chernev/prototyping-your-api-project-with-the-open-api-specification-and-node-js-tools-7cb19f47f72d#.4h6rlaw8s)\r\n\r\nAs you can see, the workflows I'm experimenting with are going around the specification as core reusable component, and then trying to integrate swagger-jsdoc or other tool in \"watch\" mode to speed up the development of the spec together with the documentation generation and deployment.\r\n\r\n## Technical aspect ##\r\n\r\nThe 2 core dependencies this module has are [doctrine](https://www.npmjs.com/package/doctrine) and [swagger-parser](https://www.npmjs.com/package/swagger-parser). So, I don't think we have to worry too much for these dependencies as probably we'll need to conditionally exchange only the swagger-parser or just use it as-is, depending on how it'll progress on the new specification.\r\n\r\nAnother question and aspect would be, would this plugin aim to handle 2 specifications at the same time? If yes, I think that i'd be convenient to change the way the module is used just a bit\r\n\r\n``` js\r\nvar swaggerSpec = swaggerJSDoc(options);\r\n```\r\nto something like\r\n\r\n``` js\r\n// Get the module\r\nconst swaggerJsdoc = require('swagger-jsdoc');\r\n// Create a parser depending on the specification and type of documentation blocks\r\nconst openApiDocsParser = swaggerJsdoc.createParser({version: 3, comments: jsdoc});\r\n// Continue as now\r\nconst openApiSpec = openApiDocsParser(options);\r\n// Or accept CPS\r\nopenApiDocsParser(options, spec => fs.writeFile('openapi.yaml', spec));\r\n```\r\nWhat I basically have in mind is that we can create a simple factory accepting some options before constructing the parser in order to be open for both new versions of the specification and different documentation styles if we would.\r\n\r\nYour comments and feedback are welcome!\r\n\r\n----------------\r\nPS:\r\n- Question at `swagger-parser`: [#62](https://github.com/BigstickCarpet/swagger-parser/issues/62)\r\n- Curated list of [OAI tools on the market](https://github.com/mermade/awesome-openapi3)"},"comment":{"url":"https://api.github.com/repos/Surnet/swagger-jsdoc/issues/comments/403951084","html_url":"https://github.com/Surnet/swagger-jsdoc/issues/65#issuecomment-403951084","issue_url":"https://api.github.com/repos/Surnet/swagger-jsdoc/issues/65","id":403951084,"node_id":"MDEyOklzc3VlQ29tbWVudDQwMzk1MTA4NA==","user":{"login":"kalinchernev","id":1923476,"node_id":"MDQ6VXNlcjE5MjM0NzY=","avatar_url":"https://avatars3.githubusercontent.com/u/1923476?v=4","gravatar_id":"","url":"https://api.github.com/users/kalinchernev","html_url":"https://github.com/kalinchernev","followers_url":"https://api.github.com/users/kalinchernev/followers","following_url":"https://api.github.com/users/kalinchernev/following{/other_user}","gists_url":"https://api.github.com/users/kalinchernev/gists{/gist_id}","starred_url":"https://api.github.com/users/kalinchernev/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/kalinchernev/subscriptions","organizations_url":"https://api.github.com/users/kalinchernev/orgs","repos_url":"https://api.github.com/users/kalinchernev/repos","events_url":"https://api.github.com/users/kalinchernev/events{/privacy}","received_events_url":"https://api.github.com/users/kalinchernev/received_events","type":"User","site_admin":false},"created_at":"2018-07-10T20:14:00Z","updated_at":"2018-07-10T20:14:00Z","author_association":"COLLABORATOR","body":"I am generally interested into getting my hands dirty on this, however I'm not sure it'll be much appreciated to be honest.\r\n\r\nOn one side, previous ideas for getting the project into better shape in general were not followed up. On another hand, looking at the issue queue, it's obvious there are numerous issues with v2 which need to be treated before v3 and not to mention there are requests to even split the CLI to make a lighter version of the package #92 :)\r\n\r\nFor me, the main question is: what's the vision of swagger-jsdoc in general? Is it meant to be maintained on first place?"}}
{"actor":{"display_login":"kalinchernev"}}