Forgefriends online coworking - February 15th 9am UTC+1


Today, Nathanaël and myself decided to have an online coworking session, starting 9am UTC+1, for the day. Anyone is welcome to join and work on this or something else, we would enjoy the company :slight_smile:

Things to do:

  • F3 and including that in an OpenAPI specification file.


Exploring how OpenAPI can be rendered in a documentation. Since Forgejo now has a new OpenAPI endpoint that may make sense.

sphinxcontrib-openapi it focuses on the API endpoints and there is no separate section that documents the schemas on their own. If someone is not interested in the API endpoints but only in the schemas, that won’t be very useful to them.


Pet Store Example - MkDocs Swagger UI Tag it inlines a Swagger style documentation which separates the schemas from the API endpoints. However it is quite inconvenient to read.


The F3 hierarchy which defines how files are organized could be defined in a OpenAPI specification. The documentation about the hierarchy could then be extracted from the OpenAPI specifications instead of being organized independently.


The format does not yet define how a hierarchy could be inlined. For instance, instead of having a file hierarchy for a project, it could be a single JSON file that includes everything, except for non-json content such as attachements, git repositories or assets that are represented by the URLs where they can be found.

File structure

F3 could define a REST API in addition to a format. Each endpoint would be a file or directory in the hierarchy.

  • /user/{id}/projects
    GET => { ids: [1, 2, 3, etc.]}
    POST => { inline JSON } => { inline JSON with id }
    POST => binary blob => id

  • /user/{id}/project/{id}
    GET => { inline JSON } or binary blob
    DELETE => 200 or 204
    PATCH => { (id: X), inline JSON } => { inline JSON } or binary blob


Use git


  • DELETE can be done twice
  • PATCH can be done twice