feat(*): support serving the API documentation page when the server starts

[iawia002]

What this PR does / why we need it:

We can now choose to serve the API docs page with the API server itself, take api-basic example project as an example, with this simple config we can let nirvana generates the API docs file and serves the API docs page when the server starts:

cfg.Configure(
	nirvana.Descriptor(v1.Descriptor(), v2.Descriptor()),
	nirvana.APIDocs("github.com/caicloud/nirvana/examples/api-basic", "/docs"),
)

Start the server, API docs related pages will serve under /docs path:

INFO  0408-16:45:44.066+08 config.go:309 | Listening on :8080
INFO  0408-16:45:44.608+08 builder.go:231 | Definitions: 1 Middlewares: 0 Path: /api/v1/applications
INFO  0408-16:45:44.608+08 builder.go:246 |   Method: Create Consumes: [application/json] Produces: [application/json]
INFO  0408-16:45:44.608+08 builder.go:231 | Definitions: 1 Middlewares: 0 Path: /api/v2/applications
INFO  0408-16:45:44.608+08 builder.go:246 |   Method: Create Consumes: [application/json] Produces: [application/json]
INFO  0408-16:45:44.608+08 builder.go:231 | Definitions: 1 Middlewares: 0 Path: /docs/api.v1.json
INFO  0408-16:45:44.608+08 builder.go:246 |   Method: Get Consumes: [] Produces: [application/json]
INFO  0408-16:45:44.608+08 builder.go:231 | Definitions: 1 Middlewares: 0 Path: /docs/api.v2.json
INFO  0408-16:45:44.608+08 builder.go:246 |   Method: Get Consumes: [] Produces: [application/json]
INFO  0408-16:45:44.608+08 builder.go:231 | Definitions: 1 Middlewares: 0 Path: /docs
INFO  0408-16:45:44.608+08 builder.go:246 |   Method: Get Consumes: [] Produces: [text/html]

And API docs files will be created in the ...examples/api-basic directory.

BTW, ReDoc has been replaced with the Swagger UI.

Which issue(s) this PR is related to (optional, link to 3rd issue(s)):

close #290

Special notes for your reviewer:

/cc @supereagle @kdada

Release note:

support serving the API documentation page when the server starts

[caicloud-bot]

[APPROVALNOTIFIER] This PR is NOT APPROVED

This pull-request has been approved by:
To fully approve this pull request, please assign additional approvers.
We suggest the following additional approver: ddysher

Assign the PR to them by writing /assign @ddysher in a comment when ready.

The full list of commands accepted by this bot can be found here.

The pull request process is described here

Needs approval from an approver in each of these files:

• OWNERS

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment

[ddysher]

IIUC, we don't require a uniform project structure now?

/assign @hezhizhen
/cc @tskdsb since you brought up API generation problem before.

[iawia002]

IIUC, we don't require a uniform project structure now?

We do have a recommended structure, for new projects, they should all use this recommended structure, but for old projects, we haven't forced them to migrate to this recommended structure.

[supereagle]

It is a good idea that serves the API docs page when the server starts. But I find that it takes a long time to generate API docs for some projects such as Cyclone, which will make the server starts very slowly.

[iawia002]

But I find that it takes a long time to generate API docs for some projects such as Cyclone, which will make the server starts very slowly.

Yes, of course, that's the price if you want to serve the API documentation page when the server starts. Nirvana needs to do a lot of analysis before starting the server.

[ddysher]

make it optional and disable by default?

…

On Tue, Apr 14, 2020 at 7:52 PM Xinzhao Xu ***@***.***> wrote: But I find that it takes a long time to generate API docs for some projects such as Cyclone, which will make the server starts very slowly. Yes, of course, that's the price if you want to serve the API documentation page when the server starts. Nirvana needs to do a lot of analysis before starting the server. — You are receiving this because you commented. Reply to this email directly, view it on GitHub <#302 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AAQXAAL443ZSSMTHYRDRWKTRMRE7VANCNFSM4MDYQQ6A> .

[iawia002]

make it optional and disable by default?

It is disabled by default.

[iawia002]

Due it may take a long time to generate API docs when the server starts in some big projects, which is unacceptable. So I'm gonna close this PR.

/close