mirrors/woodpecker
1
0
Fork 0
mirror of https://github.com/woodpecker-ci/woodpecker.git synced 2025-01-10 09:35:26 +00:00
Code Issues Projects Releases Wiki Activity
woodpecker/docs
History
Martin W. Kirst 14177635b6
Update swagger API specification (#1782) 
# Summary

This PR drops the outdated former swagger.yaml/json and introduced
automatic API document generation from Go code.
The generated code is also used to generate documentation/markdown for
the community page,
as well as enable the Woodpecker server to serve a Swagger Web UI for
manual tinkering.

I did opt-in for gin-swagger, a middleware for the Gin framework, to
ease implementation and have a sophisticated output.
This middleware only produces Swagger v2 specs. AFAIK the newer OpenApi
3x tooling is not yet that mature,
so I guess that's fine for now.

## Implemenation notes

- former swagger.json files removed
- former // swagger godocs removed
- introduced new dependency gin-swagger, which uses godoc annotations on
top of Gin Handler functions.
- reworked Makefile to automatically generate Go code for the server
- introduce new dependency go-swagger, to generate Markdown for
documentation purposes
- add a Swagger Web UI, incl. capabilities for manual API exploration
- consider relative root paths in the implementation
- write documentation for all exposed API endpoints
- incl. API docs in the community website (auto-generated)
- provide developer documentation, for the Woodpecker authors
- no other existing logic/code was intentionally changed

---------

close #292

---------

Co-authored-by: qwerty287 <80460567+qwerty287@users.noreply.github.com>
Co-authored-by: 6543 <6543@obermui.de>
2023-06-03 21:38:36 +02:00
..
docs Update swagger API specification (#1782) 2023-06-03 21:38:36 +02:00
plugins/woodpecker-plugins Add MkDocs Plugin (#1770) 2023-05-21 07:54:23 +02:00
src Docs: make sure shell examples can be copied (#1670) 2023-03-24 18:18:14 +01:00
static Improve plugins index (#1200) 2022-09-25 19:04:47 +02:00
versioned_docs/version-0.15 Remove unnecessary parenthesis (#1710) 2023-04-20 15:56:40 +02:00
versioned_sidebars Use versioned docs (#1145) 2022-09-01 01:52:52 +02:00
.gitignore [Docs] Migrate docs framework to Docusaurus (#282) 2021-09-11 17:10:32 +02:00
.prettierrc.js Improve docs (#450) 2021-10-16 21:27:51 +02:00
babel.config.js [Docs] Migrate docs framework to Docusaurus (#282) 2021-09-11 17:10:32 +02:00
docusaurus.config.js Add version notes to docs (#1592) 2023-02-28 17:30:25 +01:00
LICENSE Optimize license files (#355) 2021-09-25 15:15:54 +02:00
package.json Fix docs build (#1690) 2023-04-03 12:30:01 +02:00
pnpm-lock.yaml Fix docs build (#1690) 2023-04-03 12:30:01 +02:00
pnpm-workspace.yaml Fix docs build (#1690) 2023-04-03 12:30:01 +02:00
README.md Docs: make sure shell examples can be copied (#1670) 2023-03-24 18:18:14 +01:00
sidebars.js [Docs] Migrate docs framework to Docusaurus (#282) 2021-09-11 17:10:32 +02:00
tsconfig.json Improve docs (#450) 2021-10-16 21:27:51 +02:00
versions.json Use versioned docs (#1145) 2022-09-01 01:52:52 +02:00

README.md

Website

This website is built using Docusaurus 2, a modern static website generator.

Installation

pnpm install

Local Development

pnpm start

This command starts a local development server and opens up a browser window. Most changes are reflected live without having to restart the server.

Build

pnpm build

This command generates static content into the build directory and can be served using any static contents hosting service.

Deployment

Deployment happen via CI to woodpecker-ci.org.

To manually build the website and push it exec:

GIT_USER=woodpecker-bot USE_SSH=true DEPLOYMENT_BRANCH=master pnpm deploy