Add summary to markdown table of contents

swaggest · Aug 4, 2023 · 9303976 · 9303976
1 parent 98ccdb2
commit 9303976
Show file tree

Hide file tree

Showing 8 changed files with 92 additions and 86 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -4,6 +4,11 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.1.33] - 2023-08-04
+
+### Added
+- Summary in Markdown table of contents.
+
 ## [0.1.32] - 2023-08-04
 
 ### Added
@@ -223,6 +228,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Changed
 - Keep path parameters in operation name of PHP client.
 
+[0.1.33]: https://github.com/swaggest/swac/compare/v0.1.32...v0.1.33
 [0.1.32]: https://github.com/swaggest/swac/compare/v0.1.31...v0.1.32
 [0.1.31]: https://github.com/swaggest/swac/compare/v0.1.30...v0.1.31
 [0.1.30]: https://github.com/swaggest/swac/compare/v0.1.29...v0.1.30

diff --git a/examples/advanced-oas3.md b/examples/advanced-oas3.md
@@ -9,21 +9,21 @@ This app showcases a variety of features.
 ## Table Of Contents
 
 * [Operations](#operations)
-  - [POST `/file-multi-upload`](#examplesadvancedfilemultiuploader) 
-  - [POST `/file-upload`](#postfileupload) 
-  - [GET `/gzip-pass-through`](#getgzippassthrough) 
-  - [HEAD `/gzip-pass-through`](#headgzippassthrough) 
-  - [POST `/json-body-validation/{in-path}`](#postjsonbodyvalidationinpath) 
-  - [POST `/json-body/{in-path}`](#postjsonbodyinpath) 
-  - [POST `/json-map-body`](#postjsonmapbody) 
-  - [GET `/json-param/{in-path}`](#getjsonparaminpath) 
-  - [POST `/json-slice-body`](#postjsonslicebody) 
-  - [GET `/output-csv-writer`](#getoutputcsvwriter) 
-  - [GET `/output-headers`](#getoutputheaders) 
-  - [HEAD `/output-headers`](#headoutputheaders) 
-  - [GET `/query-object`](#getqueryobject) 
-  - [POST `/req-resp-mapping`](#postreqrespmapping) 
-  - [POST `/validation`](#postvalidation) 
+  - [POST `/file-multi-upload`](#examplesadvancedfilemultiuploader) Files Uploads With 'multipart/form-data'
+  - [POST `/file-upload`](#postfileupload) File Upload With 'multipart/form-data'
+  - [GET `/gzip-pass-through`](#getgzippassthrough) direct Gzip
+  - [HEAD `/gzip-pass-through`](#headgzippassthrough) direct Gzip
+  - [POST `/json-body-validation/{in-path}`](#postjsonbodyvalidationinpath) Request With JSON Body and non-trivial validation
+  - [POST `/json-body/{in-path}`](#postjsonbodyinpath) Request With JSON Body
+  - [POST `/json-map-body`](#postjsonmapbody) Request With JSON Map In Body
+  - [GET `/json-param/{in-path}`](#getjsonparaminpath) Request With JSON Query Parameter
+  - [POST `/json-slice-body`](#postjsonslicebody) Request With JSON Array In Body
+  - [GET `/output-csv-writer`](#getoutputcsvwriter) Output With Stream Writer
+  - [GET `/output-headers`](#getoutputheaders) Output With Headers
+  - [HEAD `/output-headers`](#headoutputheaders) Output With Headers
+  - [GET `/query-object`](#getqueryobject) Request With Object As Query Parameter
+  - [POST `/req-resp-mapping`](#postreqrespmapping) Request Response Mapping
+  - [POST `/validation`](#postvalidation) Validation
 * [Types](#types)
 
 ## <a id="operations"></a>Operations

diff --git a/examples/foobar-oas3.md b/examples/foobar-oas3.md
@@ -12,25 +12,25 @@ configurations.
 * [Security](#security)
 * [Operations](#operations)
     * Place
-      - [DELETE `/places`](#deleteplaces) 
-      - [GET `/places`](#getplaces) 
-      - [POST `/places`](#postplaces) 
+      - [DELETE `/places`](#deleteplaces) Delete Place
+      - [GET `/places`](#getplaces) Find Place
+      - [POST `/places`](#postplaces) Create Place
 
     * Foo
-      - [DELETE `/foos`](#deletefoos) 
-      - [GET `/foos`](#getfoos) 
-      - [POST `/foos`](#postfoos) 
-      - [PUT `/foos`](#putfoos) 
+      - [DELETE `/foos`](#deletefoos) Delete Foo
+      - [GET `/foos`](#getfoos) Find Foo
+      - [POST `/foos`](#postfoos) Create Foo
+      - [PUT `/foos`](#putfoos) Update Foo
 
     * Lie
-      - [POST `/internal/find-available-carrots/{mille}/{look}`](#postinternalfindavailablecarrotsmillelook) 
-      - [GET `/lies`](#getlies) 
-      - [GET `/lies/{id}`](#getliesid) 
+      - [POST `/internal/find-available-carrots/{mille}/{look}`](#postinternalfindavailablecarrotsmillelook) Find Available Carrots
+      - [GET `/lies`](#getlies) Get Lies
+      - [GET `/lies/{id}`](#getliesid) Get Lie By ID
 
     * LieAreas
-      - [GET `/lie-areas`](#getlieareas) 
-      - [POST `/lie-areas`](#postlieareas) 
-      - [PUT `/lie-areas/{mille}/{LieArea}/sync`](#putlieareasmillelieareasync) 
+      - [GET `/lie-areas`](#getlieareas) List Lie areas name
+      - [POST `/lie-areas`](#postlieareas) Create Lie Areas
+      - [PUT `/lie-areas/{mille}/{LieArea}/sync`](#putlieareasmillelieareasync) Sync Lie Area
 
 * [Types](#types)
 

diff --git a/examples/rhsm.md b/examples/rhsm.md
@@ -15,64 +15,64 @@ Base URL:https://api.access.redhat.com/management/v1
 * [Security](#security)
 * [Operations](#operations)
     * allocation
-      - [GET `/allocations`](#listallocations) 
-      - [POST `/allocations`](#postallocations) 
-      - [GET `/allocations/versions`](#getallocationsversions) 
-      - [GET `/allocations/{uuid}`](#getallocationsuuid) 
-      - [PUT `/allocations/{uuid}`](#putallocationsuuid) 
-      - [DELETE `/allocations/{uuid}`](#deleteallocationsuuid) 
-      - [POST `/allocations/{uuid}/entitlements`](#postallocationsuuidentitlements) 
-      - [PUT `/allocations/{uuid}/entitlements/{EntitlementID}`](#putallocationsuuidentitlementsentitlementid) 
-      - [DELETE `/allocations/{uuid}/entitlements/{EntitlementID}`](#deleteallocationsuuidentitlementsentitlementid) 
-      - [GET `/allocations/{uuid}/export`](#getallocationsuuidexport) 
-      - [GET `/allocations/{uuid}/export/{ExportID}`](#getallocationsuuidexportexportid) 
-      - [GET `/allocations/{uuid}/exportJob/{ExportJobID}`](#getallocationsuuidexportjobexportjobid) 
-      - [GET `/allocations/{uuid}/pools`](#getallocationsuuidpools) 
-      - [DELETE `/allocations/{uuid}/{EntitlementID}`](#deleteallocationsuuidentitlementid) 
+      - [GET `/allocations`](#listallocations) List all allocations for a user
+      - [POST `/allocations`](#postallocations) Create Satellite
+      - [GET `/allocations/versions`](#getallocationsversions) List Satellite versions
+      - [GET `/allocations/{uuid}`](#getallocationsuuid) Get an allocation by UUID
+      - [PUT `/allocations/{uuid}`](#putallocationsuuid) Update an allocation
+      - [DELETE `/allocations/{uuid}`](#deleteallocationsuuid) Remove allocation profile
+      - [POST `/allocations/{uuid}/entitlements`](#postallocationsuuidentitlements) Attach entitlement to allocation
+      - [PUT `/allocations/{uuid}/entitlements/{EntitlementID}`](#putallocationsuuidentitlementsentitlementid) Update attached entitlement to allocation
+      - [DELETE `/allocations/{uuid}/entitlements/{EntitlementID}`](#deleteallocationsuuidentitlementsentitlementid) Remove entitlement from the allocation
+      - [GET `/allocations/{uuid}/export`](#getallocationsuuidexport) Trigger allocation manifest export
+      - [GET `/allocations/{uuid}/export/{ExportID}`](#getallocationsuuidexportexportid) Download allocation manifest
+      - [GET `/allocations/{uuid}/exportJob/{ExportJobID}`](#getallocationsuuidexportjobexportjobid) Check status of allocation manifest export
+      - [GET `/allocations/{uuid}/pools`](#getallocationsuuidpools) List all pools for an allocation
+      - [DELETE `/allocations/{uuid}/{EntitlementID}`](#deleteallocationsuuidentitlementid) Remove entitlement from the allocation
 
     * cloudaccess
-      - [GET `/cloud_access_providers/enabled`](#getcloudaccessprovidersenabled) 
-      - [PUT `/cloud_access_providers/{ProviderShortName}/account`](#putcloudaccessprovidersprovidershortnameaccount) 
-      - [POST `/cloud_access_providers/{ProviderShortName}/accounts`](#postcloudaccessprovidersprovidershortnameaccounts) 
-      - [DELETE `/cloud_access_providers/{ProviderShortName}/accounts`](#deletecloudaccessprovidersprovidershortnameaccounts) 
-      - [PUT `/cloud_access_providers/{ProviderShortName}/accounts/{AccountID}`](#putcloudaccessprovidersprovidershortnameaccountsaccountid) 
-      - [PUT `/cloud_access_providers/{ProviderShortName}/accounts/{AccountID}/verification`](#putcloudaccessprovidersprovidershortnameaccountsaccountidverification) 
-      - [POST `/cloud_access_providers/{ProviderShortName}/goldimage`](#postcloudaccessprovidersprovidershortnamegoldimage) 
+      - [GET `/cloud_access_providers/enabled`](#getcloudaccessprovidersenabled) List all enabled cloud access providers for a user
+      - [PUT `/cloud_access_providers/{ProviderShortName}/account`](#putcloudaccessprovidersprovidershortnameaccount) Update provider account
+      - [POST `/cloud_access_providers/{ProviderShortName}/accounts`](#postcloudaccessprovidersprovidershortnameaccounts) Add accounts for a provider
+      - [DELETE `/cloud_access_providers/{ProviderShortName}/accounts`](#deletecloudaccessprovidersprovidershortnameaccounts) Remove a provider account
+      - [PUT `/cloud_access_providers/{ProviderShortName}/accounts/{AccountID}`](#putcloudaccessprovidersprovidershortnameaccountsaccountid) Update provider account
+      - [PUT `/cloud_access_providers/{ProviderShortName}/accounts/{AccountID}/verification`](#putcloudaccessprovidersprovidershortnameaccountsaccountidverification) Verify a provider account
+      - [POST `/cloud_access_providers/{ProviderShortName}/goldimage`](#postcloudaccessprovidersprovidershortnamegoldimage) Enable Gold image access
 
     * errata
-      - [GET `/errata`](#geterrata) 
-      - [GET `/errata/cset/{ContentSet}/arch/{Arch}`](#geterratacsetcontentsetarcharch) 
-      - [GET `/errata/{AdvisoryID}`](#geterrataadvisoryid) 
-      - [GET `/errata/{AdvisoryID}/packages`](#geterrataadvisoryidpackages) 
-      - [GET `/errata/{AdvisoryID}/systems`](#geterrataadvisoryidsystems) 
+      - [GET `/errata`](#geterrata) List all errata for a user's systems
+      - [GET `/errata/cset/{ContentSet}/arch/{Arch}`](#geterratacsetcontentsetarcharch) Get all the errata for the specified content set and arch
+      - [GET `/errata/{AdvisoryID}`](#geterrataadvisoryid) Get the details of an advisory
+      - [GET `/errata/{AdvisoryID}/packages`](#geterrataadvisoryidpackages) List all packages for an advisory
+      - [GET `/errata/{AdvisoryID}/systems`](#geterrataadvisoryidsystems) List all systems for an advisory
 
     * images
-      - [GET `/images/cset/{ContentSet}`](#getimagescsetcontentset) 
-      - [GET `/images/rhel/{Version}/{Arch}`](#getimagesrhelversionarch) 
-      - [GET `/images/{checksum}/download`](#getimageschecksumdownload) 
+      - [GET `/images/cset/{ContentSet}`](#getimagescsetcontentset) List available images in a content set
+      - [GET `/images/rhel/{Version}/{Arch}`](#getimagesrhelversionarch) List RHEL image downloads by version and architecture.
+      - [GET `/images/{checksum}/download`](#getimageschecksumdownload) Download an image by its SHA256 checksum
 
     * organization
-      - [GET `/organization`](#getorganization) 
+      - [GET `/organization`](#getorganization) Get details of the user's organization
 
     * packages
-      - [GET `/packages/cset/{ContentSet}/arch/{Arch}`](#getpackagescsetcontentsetarcharch) 
-      - [GET `/packages/{Checksum}`](#getpackageschecksum) 
-      - [GET `/packages/{checksum}/download`](#getpackageschecksumdownload) 
+      - [GET `/packages/cset/{ContentSet}/arch/{Arch}`](#getpackagescsetcontentsetarcharch) Get all the packages for the specified content set and arch.
+      - [GET `/packages/{Checksum}`](#getpackageschecksum) Get the details of a package
+      - [GET `/packages/{checksum}/download`](#getpackageschecksumdownload) Download a package by its SHA256 checksum
 
     * subscription
-      - [GET `/subscriptions`](#getsubscriptions) 
-      - [GET `/subscriptions/{SubscriptionNumber}/contentSets`](#getsubscriptionssubscriptionnumbercontentsets) 
-      - [GET `/subscriptions/{SubscriptionNumber}/systems`](#getsubscriptionssubscriptionnumbersystems) 
+      - [GET `/subscriptions`](#getsubscriptions) List all subscriptions for a user
+      - [GET `/subscriptions/{SubscriptionNumber}/contentSets`](#getsubscriptionssubscriptionnumbercontentsets) List all content sets for a subscription
+      - [GET `/subscriptions/{SubscriptionNumber}/systems`](#getsubscriptionssubscriptionnumbersystems) List all systems consuming a subscription
 
     * system
-      - [GET `/systems`](#getsystems) 
-      - [GET `/systems/{SystemUUID}`](#getsystemssystemuuid) 
-      - [DELETE `/systems/{SystemUUID}`](#deletesystemssystemuuid) 
-      - [POST `/systems/{SystemUUID}/entitlements`](#postsystemssystemuuidentitlements) 
-      - [GET `/systems/{SystemUUID}/errata`](#getsystemssystemuuiderrata) 
-      - [GET `/systems/{SystemUUID}/packages`](#getsystemssystemuuidpackages) 
-      - [GET `/systems/{SystemUUID}/pools`](#getsystemssystemuuidpools) 
-      - [DELETE `/systems/{SystemUUID}/{EntitlementID}`](#deletesystemssystemuuidentitlementid) 
+      - [GET `/systems`](#getsystems) List all systems for a user
+      - [GET `/systems/{SystemUUID}`](#getsystemssystemuuid) Get a system specified by UUID.
+      - [DELETE `/systems/{SystemUUID}`](#deletesystemssystemuuid) Remove system profile
+      - [POST `/systems/{SystemUUID}/entitlements`](#postsystemssystemuuidentitlements) Attach entitlement to system
+      - [GET `/systems/{SystemUUID}/errata`](#getsystemssystemuuiderrata) List all applicable errata for a system
+      - [GET `/systems/{SystemUUID}/packages`](#getsystemssystemuuidpackages) List all packages for a system
+      - [GET `/systems/{SystemUUID}/pools`](#getsystemssystemuuidpools) List all pools for a system
+      - [DELETE `/systems/{SystemUUID}/{EntitlementID}`](#deletesystemssystemuuidentitlementid) Remove entitlement from the system
 
 * [Types](#types)
 

diff --git a/examples/uspto-oas3.md b/examples/uspto-oas3.md
@@ -20,11 +20,11 @@ Base URL:{scheme}://developer.uspto.gov/ds-api
 
 * [Operations](#operations)
     * metadata
-      - [GET `/`](#listdatasets) 
-      - [GET `/{dataset}/{version}/fields`](#getdatasetversionfields) 
+      - [GET `/`](#listdatasets) List available data sets
+      - [GET `/{dataset}/{version}/fields`](#getdatasetversionfields) Provides the general information about the API and the list of fields that can be used to query the dataset.
 
     * search
-      - [POST `/{dataset}/{version}/records`](#postdatasetversionrecords) 
+      - [POST `/{dataset}/{version}/records`](#postdatasetversionrecords) Provides search capability for the data set with the given search criteria.
 
 * [Types](#types)
 

diff --git a/examples/xhprof-collector.md b/examples/xhprof-collector.md
@@ -10,16 +10,16 @@ Version: cli-mode
 
 * [Operations](#operations)
     * Analyze
-      - [GET `/profile`](#listprofiles) 
-      - [GET `/profile.dot`](#getprofiledot) 
-      - [GET `/profile/find-symbol`](#getprofilefindsymbol) 
-      - [GET `/profile/symbol`](#getprofilesymbol) 
-      - [GET `/top-traces`](#gettoptraces) 
+      - [GET `/profile`](#listprofiles) List Profiles
+      - [GET `/profile.dot`](#getprofiledot) Dot Graph
+      - [GET `/profile/find-symbol`](#getprofilefindsymbol) Find Symbol
+      - [GET `/profile/symbol`](#getprofilesymbol) Symbol Stat
+      - [GET `/top-traces`](#gettoptraces) Top Traces
 
     * Collect
-      - [POST `/profile`](#postprofile) 
-      - [POST `/upload/profile`](#postuploadprofile) 
-      - [POST `/upload/profiles`](#postuploadprofiles) 
+      - [POST `/profile`](#postprofile) Collect Profile
+      - [POST `/upload/profile`](#postuploadprofile) Upload Profile
+      - [POST `/upload/profiles`](#postuploadprofiles) Upload Profiles
 
 * [Types](#types)
 

diff --git a/src/Command/App.php b/src/Command/App.php
@@ -7,7 +7,7 @@
 
 class App extends Command\Application
 {
-    static $ver = 'v0.1.32';
+    static $ver = 'v0.1.33';
 
     public $phpGuzzleClient;
     public $goClient;

diff --git a/src/Markdown/APIDoc.php b/src/Markdown/APIDoc.php
@@ -215,14 +215,14 @@ public function addOperation(Operation $operation)
                 }
 
                 $this->taggedContents[$tag]->addSnippet(<<<MD
-      - [{$this->uppercase($operation->method)} `{$operation->path}`](#{$this->lowercase($funcName)}) 
+      - [{$this->uppercase($operation->method)} `{$operation->path}`](#{$this->lowercase($funcName)}) {$operation->summary}
 
 MD
                 );
             }
         } else{
             $this->tableOfContents->addSnippet(<<<MD
-  - [{$this->uppercase($operation->method)} `{$operation->path}`](#{$this->lowercase($funcName)}) 
+  - [{$this->uppercase($operation->method)} `{$operation->path}`](#{$this->lowercase($funcName)}) {$operation->summary}
 
 MD
             );