{"action":"created","issue":{"url":"https://api.github.com/repos/elastic/elasticsearch/issues/25152","repository_url":"https://api.github.com/repos/elastic/elasticsearch","labels_url":"https://api.github.com/repos/elastic/elasticsearch/issues/25152/labels{/name}","comments_url":"https://api.github.com/repos/elastic/elasticsearch/issues/25152/comments","events_url":"https://api.github.com/repos/elastic/elasticsearch/issues/25152/events","html_url":"https://github.com/elastic/elasticsearch/issues/25152","id":234803519,"number":25152,"title":"Provide OpenAPI/Swagger specification out of the box","user":{"login":"simonmit","id":4163299,"avatar_url":"https://avatars1.githubusercontent.com/u/4163299?v=3","gravatar_id":"","url":"https://api.github.com/users/simonmit","html_url":"https://github.com/simonmit","followers_url":"https://api.github.com/users/simonmit/followers","following_url":"https://api.github.com/users/simonmit/following{/other_user}","gists_url":"https://api.github.com/users/simonmit/gists{/gist_id}","starred_url":"https://api.github.com/users/simonmit/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/simonmit/subscriptions","organizations_url":"https://api.github.com/users/simonmit/orgs","repos_url":"https://api.github.com/users/simonmit/repos","events_url":"https://api.github.com/users/simonmit/events{/privacy}","received_events_url":"https://api.github.com/users/simonmit/received_events","type":"User","site_admin":false},"labels":[],"state":"open","locked":false,"assignee":null,"assignees":[],"milestone":null,"comments":0,"created_at":"2017-06-09T11:50:13Z","updated_at":"2017-06-09T11:57:13Z","closed_at":null,"body":"**Feature request:**\r\nAn Elasticsearch installation should provide a OpenAPI/Swagger specification without installing any additional plugins/configuration.\r\n\r\n**Describe the feature**:\r\nCurrently (5.x) there is no _detailed_ documentation of the REST API of Elasticsearch.\r\nWhen coding against this API it is very \"costly\" to **reveser-engineer the JSON format of the requests and responses**.\r\n\r\n*Example:*\r\n- https://www.elastic.co/guide/en/elasticsearch/reference/5.4/indices-get-index.html#indices-get-index (How does the resulting JSON look like?)\r\n- https://www.elastic.co/guide/en/elasticsearch/reference/5.4/modules-snapshots.html#_snapshot (How to parse the resulting JSON to extract the `state` field and read its value)\r\n- Errors (5xx - or 4xx errors are nicely formatted into a JSON, but how does it look exactly so it can be parsed? Always the same structure?)\r\n\r\nA simple way to document the API would be a swagger spec (or OpenAPI nowadays): Usually provide an endpoint where you can find a swagger spec in YAML format.\r\nhttps://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md\r\nhttp://swagger.io/\r\n\r\n*Excpectations:*\r\n- Every node can provide a specification that it is currently running.\r\n  - Endpoints\r\n  - Query parameters\r\n  - Request/Response JSON format\r\n  - Status Codes\r\n  - etc. (See Swagger/OpenAPI documentation)\r\n- Provide documentation for all (JSON returning) endpoints that are shipped by default with ES (e.g. do not provide X-Pack specific endpoint documentation)\r\n  - Maybe exclude `_cat` API which does not return JSON.\r\n- Add the swagger URL to the documentation (e.g. with a concrete link to Swagger UI like http://petstore.swagger.io/?url=http://localhost:9000/_openapi/spec.yaml so I can browse the specification of my locally installed ES)\r\n\r\n\r\n*Remarks:*\r\nI did not find any issues mentioning Swagger/OpenAPI\r\nI did not find any information about API documentation on the Elasticsearch Documentaion."},"comment":{"url":"https://api.github.com/repos/elastic/elasticsearch/issues/comments/307369786","html_url":"https://github.com/elastic/elasticsearch/issues/25152#issuecomment-307369786","issue_url":"https://api.github.com/repos/elastic/elasticsearch/issues/25152","id":307369786,"user":{"login":"javanna","id":832460,"avatar_url":"https://avatars2.githubusercontent.com/u/832460?v=3","gravatar_id":"","url":"https://api.github.com/users/javanna","html_url":"https://github.com/javanna","followers_url":"https://api.github.com/users/javanna/followers","following_url":"https://api.github.com/users/javanna/following{/other_user}","gists_url":"https://api.github.com/users/javanna/gists{/gist_id}","starred_url":"https://api.github.com/users/javanna/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/javanna/subscriptions","organizations_url":"https://api.github.com/users/javanna/orgs","repos_url":"https://api.github.com/users/javanna/repos","events_url":"https://api.github.com/users/javanna/events{/privacy}","received_events_url":"https://api.github.com/users/javanna/received_events","type":"User","site_admin":false},"created_at":"2017-06-09T11:57:13Z","updated_at":"2017-06-09T11:57:13Z","body":"Relates to #24065 ."}}
{"actor":{"display_login":"javanna"}}