Document API using OpenAPI

[litleleprikon]

Document API using OpenAPI

Right now Moira API do not have any documentation. I want to see beautiful interactive documentation using OpenAPI(swagger) in this repo.

I started to create the basic structure for this task and documented PUT /api/trigger/ endpoint. I assume that community can help me with this task.

To participate you need to choose an endpoint and write it in comments it below. Then you need to fork from feature/swagger branch, implement endpoint you chose and create PR to feature/swagger branch. For easier participation I created example endpoint and recommend you to follow the files structure for creating the documentation for endpoints.

Documenting the endpoint

I recommend you to follow this process during your work:

• Find the subpath of your endpoint here https://github.com/moira-alert/moira/blob/master/api/handler/handler.go#L38-L47
• Follow the function specified for your endpoint subpath and find exact function that handles your endpoint
• Create folder with name that corresponds to name of .go file with your endpoint handler in https://github.com/moira-alert/moira/tree/master/api/handler
• Check the data transfer object(DTO) for this endpoint and convert it to jsonschema using program placed below.
• Place this jsonschema in file api/{your_folder}/schemas/req_{http_method}.yml
• Describe method you interested in at api/{your_folder}/methods.yml
• Describe responses for your endpoint in api/{your_folder}/responses/{http_method}.yml
• Bind all your files using $ref
• Add endpoint path to api/main.yml and bind it with methods description using $ref
• Commit all your changes using commit message template located below
• Create pull request
• Profit!

DTO to JSONSchema converter

For easier converting I recommend you to create program at cmd/schemagen/main.go with following code:

package main

import (
	"encoding/json"
	"fmt"
	"os"

	"github.com/alecthomas/jsonschema"
	"github.com/moira-alert/moira/api/dto"
)

func main() {
	reflector := jsonschema.Reflector{
		RequiredFromJSONSchemaTags: true,
		ExpandedStruct:             true,
	}
	marshaled, err := json.Marshal(reflector.Reflect(&dto.Trigger{}))
	if err != nil {
		fmt.Println(err.Error())
		os.Exit(1)
	}
	fmt.Print(string(marshaled))
}

Put the structure you want to convert to JSONSchema instead of &dto.Trigger{} and call go run go run cmd/schemagen/main.go. The schema will be printed to stdout. Convert JSON to yml using any online converter for example https://www.json2yaml.com and use it in your endpoint definition.

Commit message template

Please use this template when you will write message for your commit.

docs(openapi): Describe {your_endpoint_http_method} {your_endpoint}

Add OpenAPI documentation for {your_endpoint_http_method} {your_endpoint}

Relates #44