{"id":13519168,"url":"https://github.com/razum2um/lurker","last_synced_at":"2025-11-11T18:31:32.423Z","repository":{"id":14495601,"uuid":"17208565","full_name":"razum2um/lurker","owner":"razum2um","description":"📖 The ultimate tool for documenting and testing APIs in Rails","archived":false,"fork":false,"pushed_at":"2020-11-17T10:12:39.000Z","size":4129,"stargazers_count":117,"open_issues_count":40,"forks_count":22,"subscribers_count":8,"default_branch":"master","last_synced_at":"2025-03-30T06:08:15.760Z","etag":null,"topics":["documentation","documentation-tool","json-schema","lurker","minitest","rails","rspec","ruby"],"latest_commit_sha":null,"homepage":"https://lurker.razum2um.me/lurker","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/razum2um.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2014-02-26T11:27:39.000Z","updated_at":"2025-02-20T07:36:12.000Z","dependencies_parsed_at":"2022-08-21T00:20:11.497Z","dependency_job_id":null,"html_url":"https://github.com/razum2um/lurker","commit_stats":null,"previous_names":[],"tags_count":21,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/razum2um%2Flurker","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/razum2um%2Flurker/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/razum2um%2Flurker/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/razum2um%2Flurker/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/razum2um","download_url":"https://codeload.github.com/razum2um/lurker/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247445681,"owners_count":20939961,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["documentation","documentation-tool","json-schema","lurker","minitest","rails","rspec","ruby"],"created_at":"2024-08-01T05:01:54.920Z","updated_at":"2025-11-11T18:31:27.387Z","avatar_url":"https://github.com/razum2um.png","language":"JavaScript","funding_links":[],"categories":["JavaScript","Testing"],"sub_categories":[],"readme":"# Lurker\n\n\u003cimg align=\"right\" width=\"94\" height=\"71\" src=\"https://cdn.rawgit.com/razum2um/lurker/master/lurker-bw.svg\"\u003e\n\nGenerates API schemas, validates code against them and creates a handy web interface for testing the API.\nTested on on Rails 4, 5, 6 and Ruby \u003e= 2.6\n\n[![Gem Version](https://badge.fury.io/rb/lurker.svg)](https://badge.fury.io/rb/lurker)\n[![Build Status][BS img]][Build Status]\n\n## Usage\n\nWrap your integration test code, which does request like this\n\n    Lurker::Spy.on do\n      get \"/api/v1/users.json\"\n    end\n\nAnd run the specs and commit your schemas. That's all, easy!\n\n## RSpec usage\n\nWrite your RSpec [controller][rspec_controller_spec] or [request][rspec_request_spec] specs as usual,\nbut add `:lurker` mark (like documented [controller example][controler_spec_example] or [request spec example][request_spec_example]).\n\n    it \"lists users\", :lurker do\n      get \"/api/v1/users.json\"\n    end\n\nNOTE: If you use `rspec-rails`, it should be required first\n\n    require 'rspec/rails'\n    require 'lurker/spec_helper'\n\n## Minitest usage\n\nYou can use [minitest-around][minitest_around] to wrap your test classes like this:\n\n    class DestroyRepoTest \u003c ActionDispatch::IntegrationTest\n      def around(\u0026block)\n        Lurker::Spy.on(\u0026block)\n      end\n    end\n\nYou also can wrap any block with API requests [manually][minitest_example].\n\n## Schemas\n\nPlease, commit your files under `Rails.root/lurker` directory.\nFeel free to edit them according to [json-schema][json_schema] standard.\nIt can be very strict and flexible if you wish: see an [example][json_schema_example],\nbut scaffolded schemas are pretty good by default.\n\n    A  lurker/ExampleApp.service.yml\n    A  lurker/api/v1/users-GET.json.yml\n    A  lurker/api/v1/users/__user_id/repos-GET.json.yml\n\nI also advise you to look on [Understanding JSON Schema][json_schema_book] book,\nit is up-to-date with draft4 and contains lot of examples.\n\n## Profit!\n\nNow, every test run lurker will look into your requests and [validate them][failed_spec_example],\nand it fails if your code changes the API!\n\n    Failure/Error: post :create [...]\n    Lurker::ValidationError:\n      Request\n      - The property '#/' contains additional properties [\"social_network\"] outside of the schema\n        when none are allowed in schema file:///.../lurker/api/v1/users-POST.json.yml#\n      Response\n      - The property '#/user/last_sign_in_at' of type String did not match the following type:\n        null in schema file:///.../lurker/api/v1/users-POST.json.yml#\n\nThe generation of live-documentation is pretty simple:\n\n    bin/lurker convert           # builds html under `Rails.root/public/lurker` to be served under `/lurker` url\n    bin/lurker convert -f pdf    # builds `Rails.root/public/lurker/snake_cased_name.pdf`\n\nFor different document root or serving URL prefix use `-o` and `-u` options accordingly.\n\nIf you want to provide additional documentation for your API (and you probably should),\nyou can use separate Markdown files in the schema folder. To generate documentation\nstubs for the current schema:\n\n    bin/lurker init_docs         # generate documentation stubs for the current schema\n\n\nLet's run your `rails s` and visit [http://localhost:3000/lurker/](http://localhost:3000/lurker/)\n(or see [demo][demo_app] for example)\n\nNow, you can test your API on-line (for real)\n\n## [Demo application][demo_app]\n\n[Custom domain][demo_app] static + demo api production endpoint (in `Sandbox` mode).\nYou can run this to get the demo running locally:\n\n    git clone https://github.com/razum2um/lurker.git\n    cd lurker\n    export BUNDLE_GEMFILE=gemfiles/rails_6.gemfile\n    bundle install\n    rake build_example_docs\n    cd tmp/lurker_app_rails_6\n    bin/rails s\n\nLurker supports multiple domains (usually `staging` and `production`) and can be deployed\nstatically everywhere as well as be served by the current `Rails` instance.\n\n## Features\n\n- [Autoscaffolding for non-covered API endpoints][controler_spec_example]\n- [Autotesting for covered endpoint once written][failed_spec_example] (both request \u0026 response!)\n- [Pretty HTML documentation based on your schemas][html_generation_example]\n- [Pretty submit form to test API endpoints (live) based on schemas][demo_live] (enter a name \u0026 press \"Submit\")\n- [Handling URLs with dynamic segments][nested_controller_spec_example] (such as `api/v1/:user_id/repos`)\n- [JSON-Schema partials][partial_example], also in YAML format ([demo][partial_example_demo])\n- [Generation PDF documentation][pdf_example] (*NOTE*: add `gem 'pdfkit'` to Gemfile)\n- [Multiple docs for many usecases][suffixes_example] (e.g `:lurker =\u003e '...'`)\n- ERB support inside `.json.yml.erb`\n- Insert custom content in Markdown into `index.html` (*NOTE*: add `gem 'kramdown'` to Gemfile)\n- Syntax highlighting for sample response (add `gem 'execjs'` to Gemfile)\n- Separate API-services generated within one test suite\n- Capistrano integration\n- JSON-Schema draft-v4 support\n- Static site deploy and milti-domain support\n- Builtin Rack middleware `Lurker::Server.to_rack` serves cached digested assets\n- [RSpec][failed_spec_example] \u0026 [Minitest][minitest_example] support\n\n## Related gems\n\n- [Swarker](https://github.com/sponomarev/swarker) converts\n  Lurker schemas to [Swagger](http://swagger.io) schema\n\n## Token authentication with sandbox\n\n`Lurker::Sandbox` allows you to test services with token authentication:\n\n    # make sure it's not production!\n    # e.g. config/environtents/staging.rb\n    config.middleware.use Lurker::Sandbox\n\nE.g. demo application on Heroku runs with it: when creating, updating repos or users\nids getting increased, but if you look into GET #index,\nnew items are NOT showing up. **This is NOT a bug!** Sequences in PostgreSQL\nare increasing notwithstanding ROLLBACK is called. As such:\n\n- run all your specs with **the same** testing token\n- ensure the same token to be accepted on your demo application\n- insert `Lurker::Sandbox` and the recorded examples should be ok to submit again\n\n## Contributions\n\n[![Code Climate][CC img]][Code Climate]\n[![Coverage Status][CS img]][Coverage Status]\n[![Inline docs](http://inch-pages.github.io/github/razum2um/lurker.png)](http://inch-pages.github.io/github/razum2um/lurker)\n[![Stories in Ready](https://badge.waffle.io/razum2um/lurker.png?label=ready\u0026title=Ready\u0026_=1)][waffle]\n\n**NOTE:** to get new version of bundled `bootstrap` or update JS/CSS,\ndon't touch files under `lib/lurker/templates/public` - they are autogenerated\nand copied to static generated site while `bin/lurker convert`\n\n    export BUNDLE_GEMFILE=gemfiles/rails_6.gemfile\n    rake assets:precompile # to build them\n\nDon't commit `lib/lurker/templates/public/**/*` to avoid conflicts.\n\n**NOTE:** if you write features keep in mind to generate different files with aruba\nbecause they are kept in the `lurker_app` directory to be deployed as a demo. Please, write\nfeatures in a way to generate **new** relevant `lurker/**/*.json.yml` files\n\n**NOTE:** template partial `submit_form.html.erb` and it's partials is a big `jsx` script for `React`\nso there are `\u003clabel htmlFor` instead of `\u003clabel for\u003e` and `\u003cdiv className` instead of `\u003cdiv class`\n### Demo app == Testing app\n\nCurrently, the testing application is using PostgreSQL because **the same** testing app is deployed to serve demo purposes.\n\nThis is also the reason not to delete anything under `lurker` directory between feature tests\nand using **different** API endpoints of the testing app. To run cucumber with clean `lurker` \u0026 `public/lurker` directories run:\n\n    CLEAN=1 export BUNDLE_GEMFILE=gemfiles/rails_6.gemfile bundle exec cucumber features\n\nBeware while writing your feature tests for PRs.\n\n## Acknowledgments\n\nThis gem is quite opinionated and relies on rails - if you're\ninterested in anything else, please take a look at [api_taster][api_taster] or [fdoc][fdoc],\nThis gem is heavily inspired by them. Thanks, @square \u0026 @fredwu\n\nAlso thanks to\n\n- [Andrey Deryabin][aderyabin] for advice\n- [Evil Martians][evil_martians] initial version sponsors\n- [React.js][reactjs] for reactive UI\n- [highlight.js][hljs] for syntax highlighting\n\n[aderyabin]: https://twitter.com/aderyabin\n[hljs]: http://highlightjs.org/\n[waffle]: https://waffle.io/razum2um/lurker\n[gh_api]: https://developer.github.com/v3/meta/\n[api_taster]: https://github.com/fredwu/api_taster\n[reactjs]: http://facebook.github.io/react/\n[fdoc]: https://github.com/square/fdoc\n[json_schema]: http://json-schema.org/\n[json_schema_example]: http://json-schema.org/example2.html\n[json_schema_book]: http://spacetelescope.github.io/understanding-json-schema/\n[evil_martians]: https://evilmartians.com/\n[rspec_controller_spec]: https://www.relishapp.com/rspec/rspec-rails/docs/controller-specs\n[rspec_request_spec]: https://www.relishapp.com/rspec/rspec-rails/docs/request-specs/request-spec\n[minitest_around]: https://github.com/splattael/minitest-around\n\n[failed_spec_example]: https://www.relishapp.com/razum2um/lurker/docs/test-endpoint\n[controler_spec_example]: https://www.relishapp.com/razum2um/lurker/docs/controller-schema-scaffolding\n[nested_controller_spec_example]: https://www.relishapp.com/razum2um/lurker/docs/controller-nested-schema-scaffolding\n[request_spec_example]: https://www.relishapp.com/razum2um/lurker/docs/request-schema-scaffolding\n[html_generation_example]: https://www.relishapp.com/razum2um/lurker/docs/html-generation\n[partial_example]: https://www.relishapp.com/razum2um/lurker/docs/partials\n[suffixes_example]: https://www.relishapp.com/razum2um/lurker/docs/request-schema-suffixes\n[minitest_example]: https://www.relishapp.com/razum2um/lurker/docs/minitest\n\n[demo_app]: https://lurker.razum2um.me\n[demo_live]: https://lurker.razum2um.me/lurker/api/v1/users-POST.html\n[pdf_example]: http://razum2um.github.io/lurker/lurker_demo_application.pdf\n[partial_example_demo]: http://razum2um.github.io/lurker/api/v1/users/__user_id/repos-POST.html\n\n[Gem Version]: https://rubygems.org/gems/lurker\n[Build Status]: https://travis-ci.org/razum2um/lurker\n[Dependency Status]: https://gemnasium.com/razum2um/lurker\n[Code Climate]: https://codeclimate.com/github/razum2um/lurker\n[Coverage Status]: https://coveralls.io/r/razum2um/lurker\n\n[BS img]: https://travis-ci.org/razum2um/lurker.png\n[CC img]: https://codeclimate.com/github/razum2um/lurker.png\n[CS img]: https://coveralls.io/repos/razum2um/lurker/badge.png?branch=master\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frazum2um%2Flurker","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frazum2um%2Flurker","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frazum2um%2Flurker/lists"}