apidoc / apidocjs.com Goto Github PK

View Code? Open in Web Editor NEW

34.0 34.0 34.0 1.98 MB

apidocjs.com Website

CSS 12.42% HTML 47.85% JavaScript 39.72%

apidocjs.com's Introduction

Important note

This project is currently not active maintained! See discussion #1436

apiDoc

apiDoc creates a documentation from API descriptions in your source code.

Documentation: apidocjs.com

Installation

$ npm install -g apidoc

Usage

Add some apidoc comments anywhere in your source code:

/**
 * @api {get} /user/:id Request User information
 * @apiName GetUser
 * @apiGroup User
 *
 * @apiParam {Number} id User's unique ID.
 *
 * @apiSuccess {String} firstname Firstname of the User.
 * @apiSuccess {String} lastname  Lastname of the User.
 */

Now generate the documentation from src/ into doc/.

$ apidoc -i src/ -o doc/

This repository contains and example folder from which you can generate a very complete documentation on an example api endpoint. It also contains best practice hints (in the footer.md file).

$ git clone https://github.com/apidoc/apidoc && cd apidoc
$ npm install --prod
$ ./bin/apidoc -i example -o /tmp/doc
$ $BROWSER /tmp/doc

Programmatic usage

You can generate the documentation programmatically:

import path from 'path'
import { createDoc } from 'apidoc'

const doc = createDoc({
  src: path.resolve(__dirname, 'src'),
  dest: path.resolve(__dirname, 'doc'), // can be omitted if dryRun is true
  // if you don't want to generate the output files:
  dryRun: true,
  // if you don't want to see any log output:
  silent: true,
})

if (typeof doc !== 'boolean') {
  // Documentation was generated!
  console.log(doc.data) // the parsed api documentation object
  console.log(doc.project) // the project information
}

Install type definitions (see @types/apidoc):

$ npm install -D @types/apidoc

Docker image

You can use apidoc in Docker like this:

# first build the image after cloning this repository
docker build -t apidoc/apidoc .
# run it
docker run --rm -v $(pwd):/home/node/apidoc apidoc/apidoc -o outputdir -i inputdir

Supported programming languages

C#, Go, Dart, Java, JavaScript, PHP, Scala (all DocStyle capable languages):
```
/**
  * This is a comment.
  */
```
Clojure:
```
;;;;
;; This is a comment.
;;;;
```
CoffeeScript:
```
###
This is a comment.
###
```
Elixir:
```
#{
# This is a comment.
#}
```
Erlang:
```
%{
% This is a comment.
%}
```

Perl

#**
# This is a comment.
#*

=pod
This is a comment.
=cut

Python
```
"""
This is a comment.
"""
```
Ruby
```
=begin
This is a comment.
=end
```

Plugins (extend apiDoc)

apiDoc will auto include installed plugins.

apidoc-plugin-schema Generates and inject apidoc elements from api schemas. npm install apidoc-plugin-schema

For details and an example on how to implement your own plugin, please view apidoc-plugin-test.

Support

Please create a new issue if you have a suggestion/question or if you found a problem/bug.

Contributing

apiDoc is a collaborative project. Pull requests are welcome. Please see the CONTRIBUTING file.

Build tools

flask-apidoc pip install flask-apidoc
grunt-apidoc npm install grunt-apidoc.
gapidoc (gulp) npm install gapidoc.
webpack-apidoc npm install --save-dev webpack-apidoc.

Integration

Converter

apidocjs.com's People

Contributors

Stargazers

Watchers

apidocjs.com's Issues

there is a way to send multiple child nodes in a json (multidimensional array) in the Request Example?
for example:
{
"person1": {"id": "1", "name1", "John", "name2": "steven", "lastname", "jhonson"},
"person2": {"id", "2", "name1", "Marly", "name2", "jay", "lastname", "jackson"}
}

Slash in groupname

How can I add slash to groupname? It is replacing by space now.

Add https on apidocjs.com

Could you add https (or renew your certificates) on apidocjs.com?

Disable AutoSort

I want to disable autosorting of my documentation entries. Is that possible?

Spanish version

I can translate apidocjs.com and pull request a file like index_es.html
Are you agree?

@apiDeprecated

I'm newbie on apidocjs but I would like use it to generate the API documentation. I found all options necessary except one to mark one method like deprecated.

Thank you for your help. (Great project !)

'@apiName watch' breaks content generation


DOESN'T WORK
/**
 * @api {put} /user/watched/:user/:repo watch
 * @apiName watch
 * @apiGroup repos
 *
 * @apiParam {String} user
 * @apiParam {String} repo
 */

WORKS
/**
 * @api {put} /user/watched/:user/:repo watch
 * @apiName watch2
 * @apiGroup repos
 *
 * @apiParam {String} user
 * @apiParam {String} repo
 */

textarea in apidocjs

How to add a textarea instead of inputbox in the html file generated.
I need to add some json as a parameter.
I can replace the textbox with textarea in the "index.html",
but when apidoc regenerates, the changes are lost, how to add the textarea in place of input box permanently,
can I use some .css/js file for the same

Generating Navagation Links Using Method Type and @apiName Instead of Description

When I generate my API documentation, the links to each individual API on the left hand side of the index page are currently being generated from the description of the API.

@api {post} /my/endpoint **this is the current link name**

I would like the link name to be a combination of the method type (in the above example post) and the @apiName. For this block comment:

@api {post} /my/endpoint description of API
@apiName Create Cake

I would like the link text for that API to be POST - Create Cake

Is there anyway to do this?

@apiPrivate doc is not correct

I think the apiPrivate doc is not correct. Here is the correction. I tried to make a pull-request but the repository does not allowed me to.

By default private APIs will be ignored. To include private APIs add --private attribute to command line.

Exemple to create a full doc with private and non-private APIs : apidoc -o private-doc --private

Exemple to create a "public" doc with only non-private APIs : apidoc -o public-doc

parser plugin 'apidefinepermission' not found in block: 1

Hey

According to the example_full, there should be a method to define permissions with @apiDefinePermission. Unfortunately all I get using that is following:

warn: parser plugin 'apidefinepermission' not found in block: 1
warn: parser plugin 'apidefinepermission' not found in block: 2
warn: parser plugin 'apidefinepermission' not found in block: 3

It will work though when using just @apiDefine. So what am I missing? Do I have to load extra plugins or what? My _apidoc.js is a complete copy of the example, so no tampering with the markup.

apiDoc-Params
@api
@apiDefine
@apiDeprecated
...

The content of @apiBody is in place but the examples appear as @apiParam instead of @apiBody.

"Integrated is an API history" sentence

The second sentence on the website:

"Integrated is an API history, with that various API version levels can be compared. So it can be retraced what changed in the API since the last version."

...needs to be rephrased. It doesn't actually make sense