Skip to content

Autogenerated docs for REST API #3522

Closed

Description

@bpmct

Currently, you can examine ./codersdk to see the various REST API queries supported by Coder. If you're interested in official documentation for the REST API (like similar to our approach for Coder Classic), please leave upvote this issue or contact us.

@mtojek:

Track progress

OSS

/api/v2:

Enterprise

/api/v2: #5625

  • /entitlements (1 method)
  • /replicas (2 methods)
  • /licenses (4 methods)
  • /organizations/{organization}/groups (3 methods)
  • /organizations/{organization}/provisionerdaemons (2 methods)
  • /groups/{group} (3 methods)
  • /workspace-quota (1 method)
  • /service-banner /appearance (2 methods)
  • /scim/v2 (6 methods)

Validation

UI improvements

Other

Activity

  1. kylecarbs commented on Aug 15, 2022

    @kylecarbs
    Member

    The godoc reference has a pretty nice view too!

  2. Emyrk commented on Aug 16, 2022

    @Emyrk
    Member

    At some point we'll have to nail down our apis and version them properly

  3. changed the title [-]Docs for REST API[/-] [+]Docs for CLI and REST API[/+] on Sep 19, 2022
  4. bpmct commented on Sep 19, 2022

    @bpmct
    MemberAuthor

    GitLab has nice auto-generated documentation for their CLI as well. https://glab.readthedocs.io/en/latest/completion/index.html

  5. changed the title [-]Docs for CLI and REST API[/-] [+]Autogenerated docs for REST API (and CLI?)[/+] on Sep 19, 2022
  6. github-actions commented on Nov 19, 2022

    @github-actions
    Contributor

    This issue is becoming stale. In order to keep the tracker readable and actionable, I'm going close to this issue in 7 days if there isn't more activity.

  7. reopened this on Dec 1, 2022
  8. mtojek commented on Dec 9, 2022

    @mtojek
    Member

    Looking into this

  9. mtojek commented on Dec 9, 2022

    @mtojek
    Member

    I checked possible options and unfortunately, the best approach seems to be tagging API operations via Go comments and generating OpenAPI/swagger description with swag.

    An alternative approach is the chi-go/docgen (official project?), which is supposed to generate Markdown/Swagger directly from chi Router, but it isn't aware of request/response entities and status codes + it leaves a lot of noise (Recover, Middleware, Logger, Prometheus, etc.).

    Screenshot 2022-12-09 at 14 01 42

    Once we have the swagger description ready, we can generate the Markdown file with widdershins. I'm not sure about the visual effect, but it looks promissing.

    EDIT:

    I'm proceeding with the comments approach.

  10. Emyrk commented on Dec 9, 2022

    @Emyrk
    Member

    I checked possible options and unfortunately, the best approach seems to be tagging API operations via Go comments and generating OpenAPI/swagger description with swag.

    I would warn about this approach. We did this in v1 and the auto generated SDK's are not ideal. Then the comments and the code go out of sync if you don't use the SDK.

    An alternative approach is the chi-go/docgen (official project?), which is supposed to generate Markdown/Swagger directly from chi Router, but it isn't aware of request/response entities and status codes + it leaves a lot of noise (Recover, Middleware, Logger, Prometheus, etc.).

    I have used a tool in the past where it looks at the request/response from our unit tests to generate docs. I wonder if we can auto gen this from our SDK, not the routes.

    Like maybe from our sdk functions won't be too bad to parse? A lot of edge cases 😢

    func (c *Client) Upload(ctx context.Context, contentType string, content []byte) (UploadResponse, error) {
    
  11. mtojek commented on Dec 9, 2022

    @mtojek
    Member

    Thanks for the good chat, @Emyrk and @johnstcn! I will go the standard way (@comment) but will implement a linter/validator. In the end, we could detect outdated undocumented API functions, wrong HTTP methods, and missing fields in request entities.

  12. mtojek commented on Dec 19, 2022

    @mtojek
    Member

    Ok, time for part 2.

    will implement a linter/validator. In the end, we could detect outdated undocumented API functions, wrong HTTP methods, and missing fields in request entities.

    plus document other API methods.

  13. changed the title [-]Autogenerated docs for REST API (and CLI?)[/-] [+]Autogenerated docs for REST API[/+] on Dec 19, 2022
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

Labels

docsArea: coder.com/docs

Type

No type

Projects

No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions