Hi Maximilian, let me start with a disclaimer. While at one time several years ago, an employer forced me to work on REST APIs, i hated it and have forgotten all about it. So it is safe to assume that i have no expertise whatsoever on REST. Yet, assuming you know about REST, what i'm saying about mdoc(7) might allow you to piece things together.
Maximilian Lorlacks wrote on Thu, Jun 13, 2019 at 12:32:04PM +0000: > I like mdoc. It feels like a natural fit for operating system > documentation. It is true that Cynthia Livingston originally developed mdoc(7) for documentation of the C and shell languages, but i do believe it can be used beyond that. That said, i can't say whether using mdoc(7) for a REST API is a good or a bad idea. From a brief perusal of the web, it appears that some recommend tools like OpenAPI (i don't fully understand what that is yet), but it appears it integrates documentation with other purposes. While in general, i strongly oppose the idea of mixing code and documentation, lacking knowledge of REST, i can't say whether my arguments really apply to REST. Using something like OpenAPI might be a good idea because documenting REST may have more requirements than documentation in general and of other languages. Or it may be a good idea to avoid such heavy-weight tools (one site i found said learning the basics of OpenAPI such that you can become productive with it will take you about two weeks of full-time work, which sound quite ridiculous to me - for comparison, i started productive work in both Python and XSLT after half a day of learning each, and those are bloody programming languages, not mere documentation tools): So avoiding OpenAPI and the like may keep stuff simple. I just don't know which of the two is the better argument. All i'm saying below applies *if* you come to the conclusion that a simple, stand-alone tool is as reasonable for REST as for any other language. > Recently however, I've been in a position to document > a REST API. I was wondering how mdoc could be made to work there. > Many of the tags do not fit: For example, there seems to be nothing > to properly map the request method (GET, POST, PUT, DELETE), Those are essentially command names in the HTTP protocol: $ telnet www.openbsd.org 80 Trying 129.128.5.194... Connected to www.openbsd.org. Escape character is '^]'. HEAD / HTTP1.1 Host: www.openbsd.org HTTP1.1 200 OK [...] But they are not the topic of the manual page you are writing, nor do they have their own manual page GET(1) or GET(3) or GET(1http). Consequently, i would simply use .Ic, "internal command" (that is, internal to the HTTP language). > the closest equivalents seem to be Dv and Ft, but neither really fit. No, those are not even in the right formatting group (in this case .Nm .Fl .Cm .Ic .Fn .Cd .Ms .Sy). Note that formatting groups are not documentated because people don't need to worry about them unless adapting mdoc(7) to a new language. Besides, .Dv should only be used for things that are defined after the fact, not for keywords built into a language, and .Ft is really only for data types. > Nm would *have* to contain the method and the path, but Nm also > requires exactly one argument to be given, so that's extra quoting > effort. Currently, i'm looking at https://bocoup.com/blog/documenting-your-api If i understand correctly, the .Nm could be, in the NAME and SYNOPSIS sections and in the running text: .Nm users .Sh SYNOPSIS .Pf / Nm users .br .Pf / Nm users Ns /: Ns Ar id .br .Pf / Nm users Ns ? Ns Cm id Ns =: Ns Ar id or .Sh SYNOPSIS .Nm /users .Nm /users Ns /: Ns Ar id .Nm /users Ns ? Ns Cm id Ns =: Ns Ar id to make .Nm work as a block macro in this special case. >From the roff(7) perspective, nothing would be wrong with ".Nm /users", the slash is just a normal character in roff(7), but man(1) doesn't like that: if the argument to man(1) contains a slash, -l is implied, so with ".Nm /users", ou would have to use man -ak Nm=/users which is admittedly awkward. Besides, you can look at the slash as punctuation in the URI rather than part of the name, and where you want to stress the slash, nothing is wrong with writing .Pf / Nm users . > With REST, you often want to provide an overview of request input > and outputs. These are somewhat analogous to function arguments > and struct output types. Often, the responses may be ad-hoc and > not really have a "type" of sorts. You mean, like the "Data Params" and "Sample Call" on the bocoup.com page i quoted? If you want to talk about an individual field, .Fa email sounds reasonable, and .Vt string for its type. To display a complete, multi-line JSON structure, you would probably use .Bd; for an example, .Bd -literal, for a syntactic display with individual elements marked up, .Bd -ragged. > You tend to need a top-level explanation that describes how error > handling works, how data is serialized (XML, JSON or something even > more horrifying) and how authentication works. Would a dedicated > introduction page be alright for that? It depends on the size of what you are writing. If you are writing many manual pages, each documenting (e.g.) one API call, and the "top-level explanation" applies to all of them, an entry page for the library as a whole might make sense, see e.g. crypto(3) - not a perfect example, but maybe good enough. Then again, error handling for a single call can maybe go into an ERRORS or DIAGNOSTICS section inside the page. > Filenames are another issue. '/' is an invalid character on UNIX > within a filename, but a REST method starts with a '/'. This will > cause the Dt and filename to always mismatch. See above for one potential solution. Even if you insist on ".Nm /users" thoughout, as long as you call the installed file "users.3" or "users.3rest", "man users" will still work, though "man /users" won't. The mandoc implementation of man(1) uses *all* names for lookup, from filename, .Dt, and NAME. Traditional man(1) implementations may use *only* the filename. > Has anyone used mdoc for REST API documentation before? How did > you make it work? If not: What would be the path of least resistance, > surely not DocBook? If you decide to do it, feel free to send drafts my way for review. If it works well, we might even include a REST style guide below http://mandoc.bsd.lv/mdoc/ Yours, Ingo
