)]}'
{"doc/contributor-guide/source/api-guides.rst":[{"author":{"_account_id":14962,"name":"ologvinova","email":"ologvinova@mirantis.com","username":"ologvinova"},"change_message_id":"34e32071dce415502d75d2e73a929cdc88a54860","unresolved":false,"context_lines":[{"line_number":16,"context_line":"WADL-to-Swagger migration tool called fairy-slipper."},{"line_number":17,"context_line":""},{"line_number":18,"context_line":"The RST conceptual and how-to files are stored in each project\u0027s"},{"line_number":19,"context_line":"doc/source/api-guide directory. These are built to locations based on the"},{"line_number":20,"context_line":"service name, such as the `Compute API Guide`_."},{"line_number":21,"context_line":""},{"line_number":22,"context_line":"You may embed annotations in your source code if you want to generate the"}],"source_content_type":"text/x-rst","patch_set":3,"id":"3afc51ec_e0baaf22","line":19,"range":{"start_line":19,"start_character":0,"end_line":19,"end_character":20},"updated":"2016-03-14 10:57:26.000000000","message":"``doc/source/api-guide``","commit_id":"616847719ed827a6de56c704c7c6acaf18de56f7"},{"author":{"_account_id":14962,"name":"ologvinova","email":"ologvinova@mirantis.com","username":"ologvinova"},"change_message_id":"34e32071dce415502d75d2e73a929cdc88a54860","unresolved":false,"context_lines":[{"line_number":20,"context_line":"service name, such as the `Compute API Guide`_."},{"line_number":21,"context_line":""},{"line_number":22,"context_line":"You may embed annotations in your source code if you want to generate the"},{"line_number":23,"context_line":"reference information. Here’s an `example patch`_ from the nova project."},{"line_number":24,"context_line":"Because we haven’t had a project do this yet completely, the build jobs still"},{"line_number":25,"context_line":"need to be written."},{"line_number":26,"context_line":""}],"source_content_type":"text/x-rst","patch_set":3,"id":"3afc51ec_85081d2f","line":23,"range":{"start_line":23,"start_character":23,"end_line":23,"end_character":29},"updated":"2016-03-14 10:57:26.000000000","message":"Here is","commit_id":"616847719ed827a6de56c704c7c6acaf18de56f7"},{"author":{"_account_id":14962,"name":"ologvinova","email":"ologvinova@mirantis.com","username":"ologvinova"},"change_message_id":"34e32071dce415502d75d2e73a929cdc88a54860","unresolved":false,"context_lines":[{"line_number":21,"context_line":""},{"line_number":22,"context_line":"You may embed annotations in your source code if you want to generate the"},{"line_number":23,"context_line":"reference information. Here’s an `example patch`_ from the nova project."},{"line_number":24,"context_line":"Because we haven’t had a project do this yet completely, the build jobs still"},{"line_number":25,"context_line":"need to be written."},{"line_number":26,"context_line":""},{"line_number":27,"context_line":"Standards for API reference in OpenStack"}],"source_content_type":"text/x-rst","patch_set":3,"id":"3afc51ec_65135167","line":24,"range":{"start_line":24,"start_character":11,"end_line":24,"end_character":18},"updated":"2016-03-14 10:57:26.000000000","message":"have not","commit_id":"616847719ed827a6de56c704c7c6acaf18de56f7"},{"author":{"_account_id":10607,"name":"Alexandra Settle","email":"a.settle@outlook.com","username":"asettle"},"change_message_id":"f4880e8d6fb13b255cc336cfe28190bcefea5ae0","unresolved":false,"context_lines":[{"line_number":35,"context_line":""},{"line_number":36,"context_line":"If your project already has WADL files, they are migrated to Swagger files with"},{"line_number":37,"context_line":"every commit to the api-site repository. Once the quality of the migration is"},{"line_number":38,"context_line":"complete, the WADL files will be deleted; you can retrieve them from Git if"},{"line_number":39,"context_line":"needed."},{"line_number":40,"context_line":""},{"line_number":41,"context_line":"If your project does not have a WADL file, then you write Swagger plus RST to"}],"source_content_type":"text/x-rst","patch_set":3,"id":"3afc51ec_b469df27","line":38,"range":{"start_line":38,"start_character":40,"end_line":38,"end_character":41},"updated":"2016-03-14 23:42:12.000000000","message":"remove the semi colon if you can :)","commit_id":"616847719ed827a6de56c704c7c6acaf18de56f7"},{"author":{"_account_id":14962,"name":"ologvinova","email":"ologvinova@mirantis.com","username":"ologvinova"},"change_message_id":"34e32071dce415502d75d2e73a929cdc88a54860","unresolved":false,"context_lines":[{"line_number":41,"context_line":"If your project does not have a WADL file, then you write Swagger plus RST to"},{"line_number":42,"context_line":"document your API calls, parameters, and reference information. You can"},{"line_number":43,"context_line":"generate Swagger from annotations or create Swagger from scratch that you"},{"line_number":44,"context_line":"store in the api-site repository in the `api-ref/swagger` directory. You should"},{"line_number":45,"context_line":"review, store, and build RST for conceptual or how-to information from within"},{"line_number":46,"context_line":"your project team’s repository."},{"line_number":47,"context_line":""}],"source_content_type":"text/x-rst","patch_set":3,"id":"3afc51ec_e0046fc1","line":44,"range":{"start_line":44,"start_character":40,"end_line":44,"end_character":57},"updated":"2016-03-14 10:57:26.000000000","message":"``api-ref/swagger``","commit_id":"616847719ed827a6de56c704c7c6acaf18de56f7"},{"author":{"_account_id":17207,"name":"Atsushi SAKAI","email":"sakaia@jp.fujitsu.com","username":"sakaia"},"change_message_id":"f48bb4dd5e6c739b75df4c2cb9b7c216cfd26b82","unresolved":false,"context_lines":[{"line_number":42,"context_line":"document your API calls, parameters, and reference information. You can"},{"line_number":43,"context_line":"generate Swagger from annotations or create Swagger from scratch that you"},{"line_number":44,"context_line":"store in the api-site repository in the `api-ref/swagger` directory. You should"},{"line_number":45,"context_line":"review, store, and build RST for conceptual or how-to information from within"},{"line_number":46,"context_line":"your project team’s repository."},{"line_number":47,"context_line":""},{"line_number":48,"context_line":"All projects should use this set of `API documentation guidelines`_ from the"}],"source_content_type":"text/x-rst","patch_set":3,"id":"1af94dfe_322fa3f7","line":45,"updated":"2016-03-17 08:48:59.000000000","message":"simple question\nIs within needed?","commit_id":"616847719ed827a6de56c704c7c6acaf18de56f7"},{"author":{"_account_id":14962,"name":"ologvinova","email":"ologvinova@mirantis.com","username":"ologvinova"},"change_message_id":"34e32071dce415502d75d2e73a929cdc88a54860","unresolved":false,"context_lines":[{"line_number":54,"context_line":"`developer.openstack.org`_."},{"line_number":55,"context_line":""},{"line_number":56,"context_line":"For the nova project, place your how-to and conceptual articles in the"},{"line_number":57,"context_line":"api-guide folder in the nova repository. Other projects can mimic these patches"},{"line_number":58,"context_line":"that created an api-guide and build jobs for the Compute api-guide. You"},{"line_number":59,"context_line":"continue to update reference information in the openstack/api-site repo."},{"line_number":60,"context_line":""}],"source_content_type":"text/x-rst","patch_set":3,"id":"3afc51ec_801c8b14","line":57,"range":{"start_line":57,"start_character":0,"end_line":57,"end_character":9},"updated":"2016-03-14 10:57:26.000000000","message":"``api-guide``","commit_id":"616847719ed827a6de56c704c7c6acaf18de56f7"},{"author":{"_account_id":10607,"name":"Alexandra Settle","email":"a.settle@outlook.com","username":"asettle"},"change_message_id":"f4880e8d6fb13b255cc336cfe28190bcefea5ae0","unresolved":false,"context_lines":[{"line_number":54,"context_line":"`developer.openstack.org`_."},{"line_number":55,"context_line":""},{"line_number":56,"context_line":"For the nova project, place your how-to and conceptual articles in the"},{"line_number":57,"context_line":"api-guide folder in the nova repository. Other projects can mimic these patches"},{"line_number":58,"context_line":"that created an api-guide and build jobs for the Compute api-guide. You"},{"line_number":59,"context_line":"continue to update reference information in the openstack/api-site repo."},{"line_number":60,"context_line":""}],"source_content_type":"text/x-rst","patch_set":3,"id":"3afc51ec_9484a3d4","line":57,"range":{"start_line":57,"start_character":0,"end_line":57,"end_character":9},"in_reply_to":"3afc51ec_801c8b14","updated":"2016-03-14 23:42:12.000000000","message":"apply to the other instances of \u0027api-guide\u0027 if doing this once","commit_id":"616847719ed827a6de56c704c7c6acaf18de56f7"},{"author":{"_account_id":14962,"name":"ologvinova","email":"ologvinova@mirantis.com","username":"ologvinova"},"change_message_id":"34e32071dce415502d75d2e73a929cdc88a54860","unresolved":false,"context_lines":[{"line_number":56,"context_line":"For the nova project, place your how-to and conceptual articles in the"},{"line_number":57,"context_line":"api-guide folder in the nova repository. Other projects can mimic these patches"},{"line_number":58,"context_line":"that created an api-guide and build jobs for the Compute api-guide. You"},{"line_number":59,"context_line":"continue to update reference information in the openstack/api-site repo."},{"line_number":60,"context_line":""},{"line_number":61,"context_line":"You can embed annotations in your source code if you want to generate the"},{"line_number":62,"context_line":"reference information. Here’s an `example patch`_ from the nova project."}],"source_content_type":"text/x-rst","patch_set":3,"id":"3afc51ec_c0721349","line":59,"range":{"start_line":59,"start_character":48,"end_line":59,"end_character":71},"updated":"2016-03-14 10:57:26.000000000","message":"``openstack/api-site`` repository","commit_id":"616847719ed827a6de56c704c7c6acaf18de56f7"},{"author":{"_account_id":14962,"name":"ologvinova","email":"ologvinova@mirantis.com","username":"ologvinova"},"change_message_id":"34e32071dce415502d75d2e73a929cdc88a54860","unresolved":false,"context_lines":[{"line_number":59,"context_line":"continue to update reference information in the openstack/api-site repo."},{"line_number":60,"context_line":""},{"line_number":61,"context_line":"You can embed annotations in your source code if you want to generate the"},{"line_number":62,"context_line":"reference information. Here’s an `example patch`_ from the nova project."},{"line_number":63,"context_line":"Because we haven’t had a project do this yet completely, the build jobs still"},{"line_number":64,"context_line":"need to be written."},{"line_number":65,"context_line":""}],"source_content_type":"text/x-rst","patch_set":3,"id":"3afc51ec_00bebbd3","line":62,"range":{"start_line":62,"start_character":23,"end_line":62,"end_character":29},"updated":"2016-03-14 10:57:26.000000000","message":"Here is","commit_id":"616847719ed827a6de56c704c7c6acaf18de56f7"},{"author":{"_account_id":14962,"name":"ologvinova","email":"ologvinova@mirantis.com","username":"ologvinova"},"change_message_id":"34e32071dce415502d75d2e73a929cdc88a54860","unresolved":false,"context_lines":[{"line_number":60,"context_line":""},{"line_number":61,"context_line":"You can embed annotations in your source code if you want to generate the"},{"line_number":62,"context_line":"reference information. Here’s an `example patch`_ from the nova project."},{"line_number":63,"context_line":"Because we haven’t had a project do this yet completely, the build jobs still"},{"line_number":64,"context_line":"need to be written."},{"line_number":65,"context_line":""},{"line_number":66,"context_line":".. _`developer.openstack.org`: http://developer.openstack.org"}],"source_content_type":"text/x-rst","patch_set":3,"id":"3afc51ec_a0cf077e","line":63,"range":{"start_line":63,"start_character":11,"end_line":63,"end_character":18},"updated":"2016-03-14 10:57:26.000000000","message":"have not","commit_id":"616847719ed827a6de56c704c7c6acaf18de56f7"},{"author":{"_account_id":10670,"name":"Michael McCune","email":"elmiko@redhat.com","username":"mimccune"},"change_message_id":"b69c4b7dded82712a8cf92251fcbf96b0759c9b2","unresolved":false,"context_lines":[{"line_number":19,"context_line":""},{"line_number":20,"context_line":"Alternatively, a project can describe their API with Swagger or OpenAPI. To"},{"line_number":21,"context_line":"learn more about the Swagger format and OpenAPI initiative, refer to"},{"line_number":22,"context_line":"https://swagger.io."},{"line_number":23,"context_line":""},{"line_number":24,"context_line":"The RST conceptual and how-to files are stored in each project\u0027s"},{"line_number":25,"context_line":"``doc/source/api-guide`` directory. These are built to locations based on the"}],"source_content_type":"text/x-rst","patch_set":6,"id":"5a18252c_2dde736d","line":22,"updated":"2016-04-12 17:59:15.000000000","message":"are we still moving ahead with some swagger implementation? (i had thought this was dead)","commit_id":"cfade259caade1801b9c6b6769cfe133ed5702bb"},{"author":{"_account_id":964,"name":"Anne Gentle","email":"annegentle@justwriteclick.com","username":"annegentle"},"change_message_id":"5db9b0fc6e5896fde48a430f9f0665549e0e86fe","unresolved":false,"context_lines":[{"line_number":19,"context_line":""},{"line_number":20,"context_line":"Alternatively, a project can describe their API with Swagger or OpenAPI. To"},{"line_number":21,"context_line":"learn more about the Swagger format and OpenAPI initiative, refer to"},{"line_number":22,"context_line":"https://swagger.io."},{"line_number":23,"context_line":""},{"line_number":24,"context_line":"The RST conceptual and how-to files are stored in each project\u0027s"},{"line_number":25,"context_line":"``doc/source/api-guide`` directory. These are built to locations based on the"}],"source_content_type":"text/x-rst","patch_set":6,"id":"5a18252c_c19ea855","line":22,"in_reply_to":"5a18252c_2dde736d","updated":"2016-04-12 20:40:02.000000000","message":"We _could_ continue to develop fairy-slipper as a swagger implementation. Do you consider any OpenStack APIs to be Swagger-compliant?","commit_id":"cfade259caade1801b9c6b6769cfe133ed5702bb"},{"author":{"_account_id":12321,"name":"Ryan Brown","email":"rybrown@redhat.com","username":"ryansb"},"change_message_id":"cfa5854c10bb81fcf1dcf6bfccb56caf0fee3a3f","unresolved":false,"context_lines":[{"line_number":34,"context_line":"~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~"},{"line_number":35,"context_line":""},{"line_number":36,"context_line":"The API working group has `API documentation guidelines`_ that all teams"},{"line_number":37,"context_line":"providing a REST API service in OpenStack must adhere to."},{"line_number":38,"context_line":""},{"line_number":39,"context_line":"How to document your OpenStack API service"},{"line_number":40,"context_line":"~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~"}],"source_content_type":"text/x-rst","patch_set":6,"id":"5a18252c_a86d5f06","line":37,"range":{"start_line":37,"start_character":42,"end_line":37,"end_character":46},"updated":"2016-04-12 14:37:24.000000000","message":"API-WG doesn\u0027t have a \"must\" mandate, the idea is to make OpenStack APIs better by working with projects, but we can\u0027t do anything to \"punish\" non-conforming APIs other than asking/reviewing nicely.","commit_id":"cfade259caade1801b9c6b6769cfe133ed5702bb"},{"author":{"_account_id":11564,"name":"Chris Dent","email":"cdent@anticdent.org","username":"chdent"},"change_message_id":"7ae1305538b1ce8e20ad1c7444a160fa94acc6b2","unresolved":false,"context_lines":[{"line_number":34,"context_line":"~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~"},{"line_number":35,"context_line":""},{"line_number":36,"context_line":"The API working group has `API documentation guidelines`_ that all teams"},{"line_number":37,"context_line":"providing a REST API service in OpenStack must adhere to."},{"line_number":38,"context_line":""},{"line_number":39,"context_line":"How to document your OpenStack API service"},{"line_number":40,"context_line":"~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~"}],"source_content_type":"text/x-rst","patch_set":6,"id":"5a18252c_c5c40194","line":37,"in_reply_to":"5a18252c_a86d5f06","updated":"2016-04-12 15:30:56.000000000","message":"Yeah, I think this would be better phrased as something inclusive:\n\n\"... guidelines`_ to which all teams providing a REST API service in OpenStack strive to follow.\"\n\nIt\u0027s sort of passive aggressive guilt inducing inclusiveness, but inclusive nonetheless.","commit_id":"cfade259caade1801b9c6b6769cfe133ed5702bb"},{"author":{"_account_id":10670,"name":"Michael McCune","email":"elmiko@redhat.com","username":"mimccune"},"change_message_id":"b69c4b7dded82712a8cf92251fcbf96b0759c9b2","unresolved":false,"context_lines":[{"line_number":34,"context_line":"~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~"},{"line_number":35,"context_line":""},{"line_number":36,"context_line":"The API working group has `API documentation guidelines`_ that all teams"},{"line_number":37,"context_line":"providing a REST API service in OpenStack must adhere to."},{"line_number":38,"context_line":""},{"line_number":39,"context_line":"How to document your OpenStack API service"},{"line_number":40,"context_line":"~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~"}],"source_content_type":"text/x-rst","patch_set":6,"id":"5a18252c_cdcfffae","line":37,"in_reply_to":"5a18252c_c5c40194","updated":"2016-04-12 17:59:15.000000000","message":"+1","commit_id":"cfade259caade1801b9c6b6769cfe133ed5702bb"},{"author":{"_account_id":1112,"name":"Everett Toews","email":"everett.toews@rackspace.com","username":"everett-toews"},"change_message_id":"8ccf1331b57d7f60b53b4ebacd5dd059e54f2593","unresolved":false,"context_lines":[{"line_number":93,"context_line":"plus RST to document your API calls, parameters, and reference information."},{"line_number":94,"context_line":"You can generate Swagger from annotations or create Swagger from scratch. You"},{"line_number":95,"context_line":"should review, store, and build RST for conceptual or how-to information from"},{"line_number":96,"context_line":"your project team’s repository."},{"line_number":97,"context_line":""},{"line_number":98,"context_line":"All projects should use this set of `API documentation guidelines`_ from the"},{"line_number":99,"context_line":"OpenStack API working group any time their service has a REST API. This"}],"source_content_type":"text/x-rst","patch_set":6,"id":"5a18252c_c76881bd","line":96,"updated":"2016-04-12 16:50:34.000000000","message":"Practically speaking, I think devs are going to need at least a bit of guidance on getting started with the above paragraph. Is there anything helpful you can link them to or point them at a project where this is already done?","commit_id":"cfade259caade1801b9c6b6769cfe133ed5702bb"}]}