{"id":16304776,"url":"https://github.com/moznion/test-jsonapi-autodoc","last_synced_at":"2025-06-18T13:34:58.270Z","repository":{"id":56831028,"uuid":"13946386","full_name":"moznion/Test-JsonAPI-Autodoc","owner":"moznion","description":"Test JSON API response and auto generate API documents","archived":false,"fork":false,"pushed_at":"2015-05-30T03:54:46.000Z","size":520,"stargazers_count":13,"open_issues_count":4,"forks_count":4,"subscribers_count":6,"default_branch":"master","last_synced_at":"2025-03-18T14:15:04.846Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://metacpan.org/release/Test-JsonAPI-Autodoc","language":"Perl","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/moznion.png","metadata":{"files":{"readme":"README.md","changelog":"Changes","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2013-10-29T04:17:59.000Z","updated_at":"2016-04-08T05:52:47.000Z","dependencies_parsed_at":"2022-08-28T20:10:28.927Z","dependency_job_id":null,"html_url":"https://github.com/moznion/Test-JsonAPI-Autodoc","commit_stats":null,"previous_names":[],"tags_count":11,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/moznion%2FTest-JsonAPI-Autodoc","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/moznion%2FTest-JsonAPI-Autodoc/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/moznion%2FTest-JsonAPI-Autodoc/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/moznion%2FTest-JsonAPI-Autodoc/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/moznion","download_url":"https://codeload.github.com/moznion/Test-JsonAPI-Autodoc/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":245013747,"owners_count":20547175,"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":[],"created_at":"2024-10-10T21:04:47.952Z","updated_at":"2025-03-22T19:35:02.528Z","avatar_url":"https://github.com/moznion.png","language":"Perl","funding_links":[],"categories":[],"sub_categories":[],"readme":"[![Build Status](https://travis-ci.org/moznion/Test-JsonAPI-Autodoc.svg?branch=master)](https://travis-ci.org/moznion/Test-JsonAPI-Autodoc) [![Coverage Status](https://img.shields.io/coveralls/moznion/Test-JsonAPI-Autodoc/master.svg)](https://coveralls.io/r/moznion/Test-JsonAPI-Autodoc?branch=master)\n# NAME\n\nTest::JsonAPI::Autodoc - Test JSON API response and auto generate API documents\n\n# SYNOPSIS\n\n    use HTTP::Request::Common;\n    use Test::More;\n    use Test::JsonAPI::Autodoc;\n\n    # JSON request\n    describe 'POST /foo' =\u003e sub {\n        my $req = POST 'http://localhost:5000/foo';\n        $req-\u003eheader('Content-Type' =\u003e 'application/json');\n        $req-\u003econtent(q{\n            {\n                \"id\": 1,\n                \"message\": \"blah blah\"\n            }\n        });\n        my $res = http_ok($req, 200, \"returns response\"); # \u003c= Check status whether 200, and generate documents.\n                                                          #    And this test method returns the response as hash reference.\n    };\n\n    # Can also request application/x-www-form-urlencoded\n    describe 'POST /bar' =\u003e sub {\n        my $req = POST 'http://localhost:3000/bar', [ id =\u003e 42, message =\u003e 'hello' ];\n        http_ok($req, 200, \"returns response\");\n    }\n\n    # And you can use Plack::Test\n    use Plack::Test;\n    use Plack::Request;\n    my $app = sub {\n        my $env = shift;\n        my $req = Plack::Request-\u003enew($env);\n        if ($req-\u003epath eq '/') {\n            return [ 200, [ 'Content-Type' =\u003e 'application/json' ], ['{ \"message\" : \"success\" }'] ];\n        }\n        return [ 404, [ 'Content-Type' =\u003e 'text/plain' ], [ \"Not found\" ] ];\n    };\n\n    my $test_app = Plack::Test-\u003ecreate($app);\n    describe 'POST /' =\u003e sub {\n        my $req = POST '/';\n        $req-\u003eheader('Content-Type' =\u003e 'application/json');\n        $req-\u003econtent(q{\n            {\n                \"id\": 1,\n                \"message\": \"blah blah\"\n            }\n        });\n        plack_ok($test_app, $req, 200, \"get message ok\");\n    };\n\n    # Of course you can use `test_psgi`\n    test_psgi $app, sub {\n        my $cb = shift;\n\n        describe 'POST /not-exist' =\u003e sub {\n            my $req = POST '/not-exist';\n            $req-\u003eheader('Content-Type' =\u003e 'application/json');\n            $req-\u003econtent(q{\n                {\n                    \"id\": 1,\n                    \"message\": \"blah blah\"\n                }\n            });\n            plack_ok($cb, $req, 404, \"not found\");\n        };\n    };\n\n# DESCRIPTION\n\nTest::JsonAPI::Autodoc tests JSON API response (only check status code).\nAnd it generates API documents according to the response automatically.\nPlease refer to [\"USAGE\"](#usage) for details.\n\n# USAGE\n\nA document will be generated if `describe` is used instead of `Test::More::subtest`.\nAnd call `http_ok` or `plack_ok` at inside of `describe`, then it tests API response\nand convert the response to markdown document.\n\nRun test as follows.\n\n    $ TEST_JSONAPI_AUTODOC=1 prove t/test.t\n\nIf `TEST_JSONAPI_AUTODOC` doesn't have true value, **documents will not generate**.\n\nThe example of `test.t` is as follows.\n\n    use HTTP::Request::Common;\n    use Test::More;\n    use Test::JsonAPI::Autodoc;\n\n    # JSON request\n    describe 'POST /foo' =\u003e sub {\n        my $req = POST 'http://localhost:5000/foo';\n        $req-\u003eheader('Content-Type' =\u003e 'application/json');\n        $req-\u003econtent(q{\n            {\n                \"id\": 1,\n                \"message\": \"blah blah\"\n            }\n        });\n        http_ok($req, 200, \"get message ok\");\n    };\n\nThe following markdown document are outputted after execution of a test.\nDocument will output to `$project_root/docs/test.md` on default setting.\n\n    generated at: 2013-11-04 22:41:10\n\n    ## POST /foo\n\n    get message ok\n\n    ### Target Server\n\n    http://localhost:5000\n\n    ### Parameters\n\n    __application/json__\n\n    - `id`: Number (e.g. 1)\n    - `message`: String (e.g. \"blah blah\")\n\n    ### Request\n\n    POST /foo\n\n    ### Response\n\n    - Status:       200\n    - Content-Type: application/json\n\n    ```json\n    {\n       \"message\" : \"success\"\n    }\n\n    ```\n\nPlease also refer to example ([https://github.com/moznion/Test-JsonAPI-Autodoc/tree/master/eg](https://github.com/moznion/Test-JsonAPI-Autodoc/tree/master/eg)).\n\n# METHODS\n\n- describe ($description, \\\\\u0026coderef)\n\n    `describe` method can be used like `Test::More::subtest`.\n    If this method is called, a document will be outputted with a test.\n\n    `$description` will be headline of markdown documents.\n\n    **\\*\\*\\* DO NOT USE THIS METHOD AS NESTING \\*\\*\\***\n\n- http\\_ok ($request, $expected\\_status\\_code, $note)\n\n    `http_ok` method tests API response (only status code).\n    and convert the response to markdown document.\n\n    `$note` will be note of markdown documents.\n\n    When this method is not called at inside of `describe`, documents is not generated.\n\n    And this method returns the response as hash reference.\n\n    Example of response structure;\n\n        $response = {\n            status       =\u003e \u003c% status code %\u003e,\n            content_type =\u003e \u003c% content type %\u003e,\n            body         =\u003e \u003c% response body %\u003e,\n        }\n\n    Moreover if `$note` is hash reference like below, you can describe each request parameters.\n\n        {\n            description =\u003e 'get message ok',\n            param_description =\u003e {\n                param1 =\u003e 'This is param1'\n                param2 =\u003e 'This is param2',\n            },\n        }\n\n    `description` is the same as the time of using as \u003c$note\u003e as scalar.\n    `param_description` contains descriptions about request parameters.\n    Now, this faculty only can describe request parameters are belonging to top level.\n    Please refer [https://github.com/moznion/Test-JsonAPI-Autodoc/tree/master/eg/http\\_with\\_req\\_params\\_description.t](https://github.com/moznion/Test-JsonAPI-Autodoc/tree/master/eg/http_with_req_params_description.t) and\n    [https://github.com/moznion/Test-JsonAPI-Autodoc/tree/master/eg/doc/http\\_with\\_req\\_params\\_description.md](https://github.com/moznion/Test-JsonAPI-Autodoc/tree/master/eg/doc/http_with_req_params_description.md).\n\n- plack\\_ok ($plack\\_app, $request, $expected\\_status\\_code, $note)\n\n    `plack_ok` method carries out almost the same operation as `http_ok`.\n    This method is for [Plack](https://metacpan.org/pod/Plack) application.\n    This method requires plack application as the first argument.\n\n    This method also returns the response as hash reference.\n\n- set\\_documents\\_path\n\n    Set the output place of a document.\n    An absolute path and a relative path can be used.\n\n- set\\_template\n\n    Set the original template. This method require the string.\n    Please refer to [\"CUSTOM TEMPLATE\"](#custom-template) for details.\n\n# REQUIREMENTS\n\nGenerated document will output to `$project_root/docs/` on default setting.\n$project\\_root means the directory on which `cpanfile` discovered while going\nback to a root directory from a test script is put.\nTherefore, **it is necessary to put `cpanfile` on a project root**.\n\n# CONFIGURATION AND ENVIRONMENT\n\n- TEST\\_JSONAPI\\_AUTODOC\n\n    Documents are generated when true value is set to this environment variable.\n\n# CUSTOM TEMPLATE\n\nYou can customize template of markdown documents.\n\nAvailable variables are the followings.\n\n- description\n- generated\\_at\n- results\n    - result.note\n    - result.path\n    - result.server\n    - result.method\n    - result.query\n    - result.request\\_content\\_type\n    - result.request\\_parameters\n    - result.is\\_plack\\_app\n    - result.status\n    - result.response\\_body\n    - result.response\\_content\\_type\n\n### Example\n\n    : if $generated_at {\n    generated at: \u003c: $generated_at :\u003e\n\n    : }\n    ## \u003c: $description :\u003e\n\n    : for $results -\u003e $result {\n    \u003c: $result.note :\u003e\n\n    : if $result.server {\n    ### Target Server\n\n    \u003c: $result.server :\u003e\n    : if $result.is_plack_app {\n\n    (Plack application)\n    : }\n\n    :}\n    ### Parameters\n\n    : if $result.request_parameters {\n        : if $result.request_content_type {\n    __\u003c: $result.request_content_type :\u003e__\n\n        : }\n    : for $result.request_parameters -\u003e $parameter {\n    \u003c: $parameter :\u003e\n    : }\n    : }\n    : else {\n    Not required\n    : }\n\n    ### Request\n\n    \u003c: $result.method:\u003e \u003c: $result.path :\u003e\n    : if $result.query {\n\n        \u003c: $result.query :\u003e\n    : }\n\n    ### Response\n\n    - Status:       \u003c: $result.status :\u003e\n    - Content-Type: \u003c: $result.response_content_type :\u003e\n\n    ```json\n    \u003c: $result.response_body :\u003e\n    ```\n    : }\n\nTemplate needs to be written by [Text::Xslate::Syntax::Kolon](https://metacpan.org/pod/Text::Xslate::Syntax::Kolon) as looking.\n\n# FAQ\n\n#### Does this module correspond to JSON-RPC?\n\nYes. It can use as [https://github.com/moznion/Test-JsonAPI-Autodoc/tree/master/eg/json\\_rpc.t](https://github.com/moznion/Test-JsonAPI-Autodoc/tree/master/eg/json_rpc.t).\n\n#### Can methods of [Test::More](https://metacpan.org/pod/Test::More) (e.g. `subtest()`) be called in `describe()`?\n\nYes, of course!\n\n# INSPIRED\n\nThis module is inspired by “autodoc”, which is written by Ruby. That is very nice RSpec extension.\n\nSee also [https://github.com/r7kamura/autodoc](https://github.com/r7kamura/autodoc)\n\n# CONTRIBUTORS\n\n- Yuuki Tsubouchi (y-uuki)\n\n# LICENSE\n\nCopyright (C) moznion.\n\nThis library is free software; you can redistribute it and/or modify\nit under the same terms as Perl itself.\n\n# AUTHOR\n\nmoznion \u003cmoznion@gmail.com\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmoznion%2Ftest-jsonapi-autodoc","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmoznion%2Ftest-jsonapi-autodoc","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmoznion%2Ftest-jsonapi-autodoc/lists"}