auto_doc_packagee

The package "AutoDocPackage" is used by the "Auto Doc" microservice for generating API documentation based on OpenApiSpex format for Elixir projects. and generate the API Docs directories and files filled with data, nested inside the respected `/documentation` directory.


License
CC-BY-NC-ND-4.0

Documentation

Auto Doc: Effortless OpenApiSpex Documentation

Welcome to Auto Doc, your ultimate solution for generating comprehensive OpenApiSpex documentation in minutes!

With Auto Doc, gone are the days of spending endless hours crafting API documentation. Simply adhere to our standardized directory hierarchy and naming conventions within your project, and let Auto Doc handle the rest.

Key Features:

  • Lightning-fast Documentation: Generate almost complete OpenApiSpex documentation in just a couple of minutes.
  • MacOS Compatibility: Auto Doc is fully compatible with MacOS. While it hasn't been tested on Windows yet, rest assured, we're working on it!
  • Seamless Integration: Easily integrate Auto Doc into your workflow via its intuitive API.
  • Subscription-based Service: Enjoy the convenience of a subscription-based microservice, offering you a solid foundation for writing professional API Docs while saving you valuable time and resources, all for less than the cost of an hour's work (10€) per month.
  • Upgrade your API documentation experience with Auto Doc today and witness unparalleled efficiency and professionalism in your projects.

Installation

Add the following dependencies to mix.exs file deps/0 function.

Note: We'll need Jason and HTTPoison to format the data and do the API calls.

{:jason, "~> 1.2"},
{:httpoison, "~> 2.0"},
{:auto_doc_package, git: "https://github.com/zen-dev-lab/auto_doc_package"}

Registration

  1. Go to auto-doc.fly.dev
  2. Click Sign in
  3. Register via Github OAuth
  4. Being forwarded to your dashboard page where a personal user token can be seen(important for later)

Register via Github

Personal Github Access Token

For Authorizing API calls to Auto Doc, you'll need a personal access token.

  1. Navigate to settings/tokens page here
  2. Click Generate new token
  3. Give it some name and set your expiration date to 90 days or more
  4. Click Generate token
  5. Copy your personal access token (important in for the next step)

Github access token

Setup ENV Variables

In your .env file, add the following ENV Variables:

# The Token shown in your Dashboard
export AUTO_DOC_USER_TOKEN="your-user-token-here"
# The Github Access Token we just created in the previous step
export GITHUB_ACCESS_TOKEN="your-access-token-here"

To apply the changes done to the file, run the following command in your IDE terminal:

source .env

That's it! You can now use the package and API. 🙌

AutoDocPackage usage

  • First, start your Interactive Elixir shell by running the following command in your IDE's terminal

    iex -S mix
  • Then, we need to pick the documentation directory and the controller to create OpenApiSpex docs for.

  • Copy the relative paths to both the directory and the controller file and assign them to variables.

    documentation_path = "auto_doc/lib/auto_doc_web/documentation"
    controller_path = "auto_doc/lib/auto_doc_web/controllers/users/user_controller.ex"

    copy relative paths

  • Now, execute the function written below

    AutoDocPackage.Requests.gen_example_data_file(documentation_path, controller_path)
  • Notice that under the lib/ directory a new file with the name example_data.json has been created. example_file generated

  • Open it and check its content. example_data filecontent

  • It contains two types of keys:

    • special keys(start and end with __) which musn't be edited.

      special keys

    • operation keys(each key corresponds to a new undocumented action in your controller)

      operation keys

  • With the example_data.json file present, what's left to do is add the params/response payloads for each action key and then run the gen_api_spex/1 commmand with the corresponding argument.

    • There are three possible arguments for that command

      • :params or "params" -> states that params payloads have been passed and should create the new Params modules
      • :response or "response" -> states that response payloads have been passed and should create the new Response modules
      • :operations or "operations" -> states that the new Params/Response modules have been created and should add the new operation functions (and their aliases)
    • Generate response modules

      • Pass the response payloads as described earlier and run

        AutoDocPackage.Requests.gen_api_spex(:response)

        response payloads in example_data

      • Then, your response.ex file will be generated or the new modules will be appended to the existing file. (Zoom in to check the image in details) Response modules OpenApiSpex

    • Generate params modules:

      • Same as the previous step but you pass the params payloads and run the command with :params argument

        AutoDocPackage.Requests.gen_api_spex(:params)

        params payload in example_data

      • Important! -> For actions which don't have params payload(such as GET requests), then remove the respective keys from the example_data.json file to avoid unnecessary Params modules generation. This behaviour is shown in the example image(show and index keys have been removed).

    • Generate operations module/functions:

      • After completing the previous two steps, simply run

         AutoDocPackage.Requests.gen_api_spex(:operations)

        Operations module

      • You'll notice that the new operations functions have been added to the end of your operations.ex file's Operations module and the params/response aliases have also been included.

      • Default errors/ directory will be created in the root of your documentation/ dir. It'll contain a default error file handling status 401.

        not authenticated error file

      • If you don't have errors.ex file present, a default one will be generated to handle statuses 404 and 422 which are aliased and used in the Operations module. If the file exists, nothing will happen, meaning that the content will not be overwritten.

        default errors file

      • You're done! Your OpenApiSpex Documentation is completed (excluding any missing fields and description writing)

    • Important!

      • Use as detailed payloads as possible since they're the most important part of types/values generation and mapping. Anything missing in the payload in return will be missing in the generated documentation.

      • Descriptions are still written manually and for that case, search for the TOWRITE keyword and change all occurences with your custom text.

        towrite example

      • If a type wasn't recognized upon generation, it'll have value of :unknown and should be changed to the proper value manually.

        type unknown

      • In params payload, if one of the main keys matches the model(schema)'s field name, its default and values will be mapped and also be added to the API Docs automatically.

        Note: It's not 100% foolproof, but we're working on improving it.

      • Supports Documentation versioning in the path and module in format: your_app_web/access_type/version/...

        # Private V2 example | access_type = "private" ; version = "v2"
        documentation_path = "auto_doc/lib/auto_doc_web/private/v2/documentation"
        controller_path = "auto_doc/lib/auto_doc_web/private/v2/controllers/users/user_controller.ex"
        # Public V1 example | access_type = "public" ; version = "v1"
        documentation_path = "auto_doc/lib/auto_doc_web/public/v1/documentation"
        controller_path = "auto_doc/lib/auto_doc_web/public/v1/controllers/users/user_controller.ex"