diff --git a/.github/workflows/update-doc.yaml b/.github/workflows/update-doc.yaml index bd085e988..ebb5e3612 100644 --- a/.github/workflows/update-doc.yaml +++ b/.github/workflows/update-doc.yaml @@ -43,8 +43,10 @@ jobs: sparse-checkout: | hack/ docs/ + - name: Get all tags run: git fetch --prune --unshallow --tags + - name: Initialize themes run: | @@ -60,11 +62,12 @@ jobs: # This is used to keep up-to-date installation instructions. cd hack/doc-site/hugo LATEST_RELEASE=$(git describe --tags --abbrev=0) + VERSION_MESSAGE="Documentation set for latest master." ROOT=$(git rev-parse --show-toplevel) REQUIRED_GO_VERSION=$(grep "^go\s" "${ROOT}"/go.mod|cut -d" " -f2) printf \ - "params:\n goswagger:\n goVersion: '%s'\n latestRelease: '%s'\n" \ - "${REQUIRED_GO_VERSION}" "${LATEST_RELEASE}" > goswagger.yaml + "params:\n goswagger:\n goVersion: '%s'\n latestRelease: '%s'\n versionMessage: '%s'\n" \ + "${REQUIRED_GO_VERSION}" "${LATEST_RELEASE}" "${VERSION_MESSAGE}" > goswagger.yaml - name: Build site with Hugo @@ -88,11 +91,18 @@ jobs: uses: actions/upload-pages-artifact@v3 with: path: hack/doc-site/hugo/public + - + name: Debug + run: | + echo "${{ github.event_name }}" + echo "${{ github.event.action }}" deploy-doc: + if: ${{ github.event_name != 'pull_request_target' }} environment: name: github-pages url: ${{ steps.deployment.outputs.page_url }} + trigger: $${{ github.event_name }} runs-on: ubuntu-latest needs: build-doc steps: diff --git a/docs/_index.md b/docs/_index.md index 859463381..6e904193b 100644 --- a/docs/_index.md +++ b/docs/_index.md @@ -5,16 +5,22 @@ draft: true weight: 1 --- {{}} - -# Swagger 2.0 [![Build Status](https://circleci.com/gh/go-swagger/go-swagger.svg?style=shield)](https://circleci.com/gh/go-swagger/go-swagger) [![Build status](https://ci.appveyor.com/api/projects/status/x377t5o9ennm847o/branch/master?svg=true)](https://ci.appveyor.com/project/casualjim/go-swagger/branch/master) [![codecov](https://codecov.io/gh/go-swagger/go-swagger/branch/master/graph/badge.svg)](https://codecov.io/gh/go-swagger/go-swagger) [![GitHub version](https://badge.fury.io/gh/go-swagger%2Fgo-swagger.svg)](https://badge.fury.io/gh/go-swagger%2Fgo-swagger) + +{{< hint "info" >}} +{{< param goswagger.versionMessage >}} +{{< /hint >}} + +# Swagger 2.0 [![Run CI](https://github.com/go-swagger/go-swagger/actions/workflows/test.yaml/badge.svg)](https://github.com/go-swagger/go-swagger/actions/workflows/test.yaml) [![codecov](https://codecov.io/gh/go-swagger/go-swagger/branch/master/graph/badge.svg)](https://codecov.io/gh/go-swagger/go-swagger) [![GitHub version](https://badge.fury.io/gh/go-swagger%2Fgo-swagger.svg)](https://badge.fury.io/gh/go-swagger%2Fgo-swagger) + [![Slack Status](https://slackin.goswagger.io/badge.svg)](https://slackin.goswagger.io) [![license](http://img.shields.io/badge/license-Apache%20v2-orange.svg)](https://raw.githubusercontent.com/swagger-api/swagger-spec/master/LICENSE) [![GoDoc](https://godoc.org/github.com/go-swagger/go-swagger?status.svg)](http://godoc.org/github.com/go-swagger/go-swagger) [![Docker Repository on Quay](https://quay.io/repository/goswagger/swagger/status "Docker Repository on Quay")](https://quay.io/repository/goswagger/swagger) [![FOSSA Status](https://app.fossa.io/api/projects/git%2Bgithub.com%2Fgo-swagger%2Fgo-swagger.svg?type=shield)](https://app.fossa.io/projects/git%2Bgithub.com%2Fgo-swagger%2Fgo-swagger?ref=badge_shield) -[![GolangCI](https://golangci.com/badges/github.com/go-swagger/go-swagger.svg)](https://golangci.com) [![Go Report Card](https://goreportcard.com/badge/github.com/go-swagger/go-swagger)](https://goreportcard.com/report/github.com/go-swagger/go-swagger) +[![Open SSF Scorecard](https://api.securityscorecards.dev/projects/github.com/go-swagger/go-swagger/badge)](https://securityscorecards.dev/viewer/?uri=github.com/go-swagger/go-swagger) + This package contains a golang implementation of Swagger 2.0 (aka [OpenAPI 2.0](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md)): it knows how to serialize and deserialize swagger specifications. @@ -51,12 +57,14 @@ The go-openapi community actively continues bringing fixes and enhancements to t There is still much room for improvement: contributors and PR's are welcome. You may also get in touch with maintainers on [our slack channel](https://slackin.goswagger.io). ## Documentation - +Latest master: + +Documentation sets for released versions: +* Latest release: ## FAQ -Q&A contributed by the community: - +[Q&A contributed by the community](faq) ## How is this different from go generator in swagger-codegen? **tl;dr** The main difference at this moment is that this one actually works... @@ -77,7 +85,7 @@ Further, the go server generated by swagger-codegen is mostly a stub. ## What's inside? -Here is an outline of available features (see the full list [here](https://goswagger.io/features.html)): +Here is an outline of available features (see the full list [here](features.md)): - An object model that serializes swagger-compliant yaml or json - A tool to work with swagger @@ -97,14 +105,14 @@ Here is an outline of available features (see the full list [here](https://goswa There is more to that... -- A [typed JSON Schema implementation](https://goswagger.io/use/model.html), supporting most Draft 4 features +- A [typed JSON Schema implementation](reference/models), supporting most Draft 4 features - Extended string and numeric formats: [strfmt](https://github.com/go-openapi/strfmt) - Utilities to work with JSON, convert data types and pointers: [swag](https://github.com/go-openapi/swag) - A jsonschema (Draft 4) validator, with full $ref support: [validate](https://github.com/go-openapi/validate) - Custom validation interface ## Installing -`go-swagger` is available as binary or docker releases as well as from source: [more details](https://goswagger.io/install.html). +`go-swagger` is available as binary or docker releases as well as from source: [more details](install). ## Use-cases The main package of the toolkit, go-swagger/go-swagger, provides command line tools to help working with swagger. @@ -113,7 +121,7 @@ The toolkit is highly customizable and allows endless possibilities to work with Beside the go-swagger CLI tool and generator, the [go-openapi packages](https://github.com/go-openapi) provide modular functionality to build custom solutions on top of OpenAPI. -The CLI supports shell autocompletion utilities: see [here](https://goswagger.io/cli_helpers.html). +The CLI supports shell autocompletion utilities: see [here](usage/cli_helpers.md). ### Serve specification UI Most basic use-case: serve a UI for your spec: @@ -123,21 +131,21 @@ swagger serve https://raw.githubusercontent.com/swagger-api/swagger-spec/master/ ``` ### Validate a specification -To [validate](https://goswagger.io/usage/validate.html) a Swagger specification: +To [validate](usage/validate.md) a Swagger specification: ``` swagger validate https://raw.githubusercontent.com/swagger-api/swagger-spec/master/examples/v2.0/json/petstore-expanded.json ``` ### Generate an API server -To generate a [server for a swagger spec](https://goswagger.io/generate/server.html) document: +To generate a [server for a swagger spec](generate/server.md) document: ``` swagger generate server [-f ./swagger.json] -A [application-name [--principal [principal-name]] ``` ### Generate an API client -To generate a [client for a swagger spec](https://goswagger.io/generate/client.html) document: +To generate a [client for a swagger spec](generate/client.md) document: ``` swagger generate client [-f ./swagger.json] -A [application-name [--principal [principal-name]] @@ -148,7 +156,7 @@ To generate a [CLI for a swagger spec](https://github.com/go-swagger/go-swagger/ swagger generate cli [-f ./swagger.json] -A [application-name [--principal [principal-name]] ``` ### Generate a spec from source -To generate a [swagger spec document for a go application](https://goswagger.io/generate/spec.html): +To generate a [swagger spec document for a go application](generate-spec/spec.md): ``` swagger generate spec -o ./swagger.json @@ -163,7 +171,7 @@ swagger generate model --spec={spec} ### Transform specs -There are [several commands](https://goswagger.io/use/transform.html) allowing you to transform your spec. +There are [several commands](reference/transform) allowing you to transform your spec. Resolve and expand $ref's in your spec as inline definitions: ``` diff --git a/hack/doc-site/hugo/goswagger.yaml b/hack/doc-site/hugo/goswagger.yaml index 7a5b67a02..2590f5a73 100644 --- a/hack/doc-site/hugo/goswagger.yaml +++ b/hack/doc-site/hugo/goswagger.yaml @@ -2,3 +2,4 @@ params: goswagger: goVersion: '1.20' latestRelease: 'v0.30.5' + versionMessage: "Documentation set for latest master"