Key Information

Register
Submit
The challenge is finished.

Challenge Overview

1. Context:

Project Context

To aid in our transition to new, modern APIs for the Topcoder platform, we want to define a good process for documenting those APIs, both with regular markdown and with auto-generated API documentation from Swagger.

Challenge Context

This challenge will help us investigate what's possible and how we can potentially implement what we need.  This challenge can be considered a proof of concept, and competitors are free to use one of these available libraries:

2. Expected Outcome:

The outcome of this challenge is a better idea of what's possible and how we can meet the requirements that Topcoder expects for static content and generate API documentation using one of the tools listed above.

3. Challenge Details

Individual requirements

We're looking for a solution that can:
  • Automatically generate static content from Markdown files stored in the "docs" folder of a repository
  • Automatically generate Swagger API docs
  • Publish the docs to a specified path on a server

Multiple repositories


Note that the repositories need to be configurable and that multiple repositories may need to be pulled to collect the docs necessary.  For instance, only our Swagger docs are stored with the individual code repositories.  The Markdown documentation is going to be stored in a separate repository in the final deployment.

Paths


The published path structure should be configurable somehow.  Either we can configure this in a separate file, or we can structure the markdown files in the docs folder of a repository in a specific way to have them map to published routes.  Either option is acceptable, as long as the solution is easy to use and flexible.

Links


To go along with the published path structure, we want to make sure we can link from the Swagger API docs to the static Markdown docs and vice versa.  Please show examples of linking back and forth between them.

Example

As an example, see this page for something we may want to generate via Markdown:

https://stripe.com/docs/payments

And corresponding API docs:

https://stripe.com/docs/api/balance

Here are a few repositories that we will be planning to integrate with the tool.  Each repo should contain Swagger docs, if you want to use those as examples in your submission.
Note that these example repos only contain Swagger docs - they do not have Markdown documentation yet.  Please provide some relatively detailed sample Markdown in your submission with text formatting, tables, navigation, and images shown.

Technology Stack

The final solution will run on AWS, but we don't have a strict technology stack just yet.  Please plan on a Linux-based OS and a recent Git client.  Repositories are normally hosted on Github.

Final Deliverables

  • Deployment documentation detailing how to install your chose library and configuring it to generate:
    • Static HTML from Markdown files
    • Swagger docs
  • Validation documentation detailing how to ensure that the docs are generated properly and can be browsed
  • Configuration and any code needed to meet the requirements above

4. Scorecard Aid:

Judging Criteria

  • Major requirements are that static documentation *and* Swagger is generated properly and hosted locally and can be browsed through a configurable path
  • Minor requirements include links between the documentation and Swagger, and documentation of approaches tried, if you evaluated more than one library of the 3 that were allowed.


Final Submission Guidelines

Please see above

ELIGIBLE EVENTS:

2020 Topcoder(R) Open

REVIEW STYLE:

Final Review:

Community Review Board

Approval:

User Sign-Off

SHARE:

ID: 30122288