FAI-2039 Swagger annotations for GetVacancyResponse and CreateVacancyRequest

src/Vacancies/SFA.DAS.Vacancies.Api.UnitTests/Models/WhenMappingFromMediatorResponseToGetVacancyResponse.cs

@@ -59,10 +59,7 @@ public void Then_The_Fields_Are_Mapped(GetVacancyQueryResult source, int ukprn)
             actual.Course.LarsCode.Should().Be(source.Vacancy.StandardLarsCode);
             actual.Wage.WageAmount.Should().Be(source.Vacancy.WageAmount);
             actual.Wage.WageType.Should().Be((WageType)source.Vacancy.WageType);
-            actual.Wage.WageUnit.Should().Be((WageUnit)source.Vacancy.WageUnit);
             actual.Wage.WageAdditionalInformation.Should().Be(source.Vacancy.WageText);
-            actual.Wage.WageAmountLowerBound.Should().Be(source.Vacancy.WageAmountLowerBound);
-            actual.Wage.WageAmountUpperBound.Should().Be(source.Vacancy.WageAmountUpperBound);
             actual.Ukprn.Should().Be(ukprn);
             actual.VacancyReference.Should().Be(source.Vacancy.VacancyReference.Replace("VAC", ""));
             actual.ClosingDate.Should().Be(source.Vacancy.ClosingDate.AddDays(1).Subtract(TimeSpan.FromSeconds(1)));

src/Vacancies/SFA.DAS.Vacancies.Api.UnitTests/Models/WhenMappingFromMediatorResponseToGetVacancyWageItem.cs

@@ -16,8 +16,6 @@ public void Then_The_Values_Are_Mapped(GetVacanciesListItem source)
             actual.WageAmount.Should().Be(source.WageAmount);
             actual.WageType.Should().Be((WageType)source.WageType);
             actual.WageAdditionalInformation.Should().Be(source.WageText);
-            actual.WageAmountUpperBound.Should().Be(source.WageAmountUpperBound);
-            actual.WageAmountLowerBound.Should().Be(source.WageAmountLowerBound);
             actual.WorkingWeekDescription.Should().Be(source.WorkingWeek);
         }
     }

src/Vacancies/SFA.DAS.Vacancies.Api/Models/GetVacanciesListResponse.cs

@@ -27,89 +27,161 @@ public static implicit operator GetVacanciesListResponse(GetVacanciesQueryResult
     }
     public class GetVacanciesListResponseItem
     {
-       public DateTime ClosingDate { get; set; }    
-       public string Description { get; set; }
-       public string EmployerName { get; set; }
-       public decimal HoursPerWeek { get; set; }
-       public bool IsDisabilityConfident { get; set; }
-       public  bool IsNationalVacancy { get; set; }
-       public long NumberOfPositions { get; set; }
-       public DateTime PostedDate { get; set; }
-       public string ProviderName { get; set; }
-       public DateTime StartDate { get; set; }
-       public string Title { get; set; }
-       public int Ukprn { get; set; }
-       public string VacancyReference { get; set; }
-       public string VacancyUrl { get; set; }
+        /// <summary>
+        /// The title for the apprenticeship vacancy. Will be less than or equal to 100 characters.
+        /// </summary>
+        public string Title { get; set; }
+        /// <summary>
+        /// A short summary of the overall apprenticeship. Will be less than or equal to 350 characters.
+        /// </summary>
+        public string Description { get; set; }
+        /// <summary>
+        /// The number of apprentices being recruited for the apprenticeship. Will be 1 or higher.
+        /// </summary>
+        public long NumberOfPositions { get; set; }
+        /// <summary>
+        /// The date the apprenticeship was added to Find an apprenticeship.
+        /// </summary>
+        /// <example>2019-08-24T:14:15:22Z</example>
+        public DateTime PostedDate { get; set; }
+        /// <summary>
+        /// The last date people can apply for the apprenticeship. Will always be more than 2 weeks after the posted date.
+        /// </summary>
+        /// <example>2019-08-24T:14:15:22Z</example>
+        public DateTime ClosingDate { get; set; }    
+        /// <summary>
+        /// The date the company plans for the apprenticeship to start.
+        /// </summary>
+        /// <example>2019-08-24T:14:15:22Z</example>
+        public DateTime StartDate { get; set; }
+        public GetVacancyWageItem Wage { get; set; }
+        /// <summary>
+        /// The total number of hours per week. This includes both work and training.
+        /// </summary>
+        public decimal HoursPerWeek { get; set; }
+        /// <summary>
+        /// How long the apprenticeship will be. Will be in months, written as a string of text.
+        /// </summary>
+        /// <example>21 months</example>
+        public string ExpectedDuration { get ; set ; }
+        public GetVacancyAddressItem Address { get; set; }
+        public VacancyLocation Location { get; set; }
+        /// <summary>
+        /// If you provide a `lat` and `lon` for a location when using `GET list of vacancies` or `GET vacancy by reference number`, this will be the distance between the apprenticeship and your defined location. Will be in miles.
+        /// </summary>
+        public decimal? Distance { get ; set ; }
+        /// <summary>
+        /// The name of the company the apprentice will work at.
+        /// </summary>
+        public string EmployerName { get; set; }
+        /// <summary>
+        /// The web address for the company the apprentice will work at.
+        /// </summary>
+        public string EmployerWebsiteUrl { get ; set ; }
+        /// <summary>
+        /// A named contact a person can use to ask questions about the apprenticeship before applying. This contact can be from either the employer or training provider.
+        /// </summary>
+        public string EmployerContactName { get ; set ; }
+        /// <summary>
+        /// A phone number a person can use to ask questions about the apprenticeship before applying. This contact can be from either the employer or training provider.
+        /// </summary>
+        public string EmployerContactPhone { get ; set ; }
+        /// <summary>
+        /// An email address a person can use to ask questions about the apprenticeship before applying. This contact can be from either the employer or training provider.
+        /// </summary>
+        public string EmployerContactEmail { get ; set ; }
+        public GetVacancyCourseItem Course { get; set; }
+        /// <summary>
+        /// Whether an apprenticeship is ‘intermediate’ (level 2), ‘advanced’ (level 3), ‘higher’ (level 4 to 5) or ‘degree’ (level 6 or 7).
+        /// </summary>
+        public string ApprenticeshipLevel { get ; set ; }
+        /// <summary>
+        /// The name of the apprenticeship’s training provider.
+        /// </summary>
+        public string ProviderName { get; set; }
+        /// <summary>
+        /// The UK provider reference number (UKRPN) for the apprenticeship’s training provider.
+        /// </summary>
+        public int Ukprn { get; set; }
+        /// <summary>
+        /// Says whether the employer is part of the Department for Work and Pension’s Disability Confident scheme.
+        /// </summary>
+        public bool IsDisabilityConfident { get; set; }
+        /// <summary>
+        /// The address for the apprenticeship’s vacancy on Find an apprenticeship.
+        /// </summary>
+        public string VacancyUrl { get; set; }
+        /// <summary>
+        /// The unique reference code for the vacancy on Find an apprenticeship.
+        /// </summary>
+        public string VacancyReference { get; set; }
+        public  bool IsNationalVacancy { get; set; }
 
-       public GetVacancyCourseItem Course { get; set; }
-       public GetVacancyWageItem Wage { get; set; }
-       public VacancyLocation Location { get; set; }
-       public GetVacancyAddressItem Address { get; set; }
-       public decimal? Distance { get ; set ; }
-
-       public string EmployerContactPhone { get ; set ; }
-       public string EmployerContactName { get ; set ; }
-       public string EmployerContactEmail { get ; set ; }
-       public string EmployerWebsiteUrl { get ; set ; }
-       public string ApprenticeshipLevel { get ; set ; }
-       public string ExpectedDuration { get ; set ; }
-
-       public static implicit operator GetVacanciesListResponseItem(GetVacanciesListItem source)
-       {
-           return new GetVacanciesListResponseItem
-           {
-               ClosingDate = source.ClosingDate.AddDays(1).Subtract(TimeSpan.FromSeconds(1)),
-               Description = source.Description,
-               EmployerName = source.IsEmployerAnonymous ? source.AnonymousEmployerName : source.EmployerName,
-               HoursPerWeek = source.HoursPerWeek,
-               IsDisabilityConfident = source.IsDisabilityConfident,
-               IsNationalVacancy = source.VacancyLocationType != null && source.VacancyLocationType.Equals("National", StringComparison.CurrentCultureIgnoreCase),
-               NumberOfPositions = source.NumberOfPositions,
-               PostedDate = source.PostedDate,
-               ProviderName = source.ProviderName,
-               StartDate = source.StartDate,
-               Title = source.Title,
-               Ukprn = int.Parse(source.Ukprn),
-               VacancyReference = source.VacancyReference.Replace("VAC",""),
-               VacancyUrl = source.VacancyUrl,
-               Course = source,
-               Wage = source,
-               Distance = source.Distance,
-               Address = source,
-               EmployerWebsiteUrl = source.EmployerWebsiteUrl,
-               EmployerContactEmail = source.EmployerContactEmail,
-               EmployerContactName = source.EmployerContactName,
-               EmployerContactPhone = source.EmployerContactPhone,
-               ApprenticeshipLevel = source.ApprenticeshipLevel,
-               ExpectedDuration = source.ExpectedDuration,
-               Location = new VacancyLocation
-               {
-                   Lat = source.Location.Lat,
-                   Lon = source.Location.Lon
-               }
-           };
-       }
+
+
+        public static implicit operator GetVacanciesListResponseItem(GetVacanciesListItem source)
+        {
+            return new GetVacanciesListResponseItem
+            {
+                ClosingDate = source.ClosingDate.AddDays(1).Subtract(TimeSpan.FromSeconds(1)),
+                Description = source.Description,
+                EmployerName = source.IsEmployerAnonymous ? source.AnonymousEmployerName : source.EmployerName,
+                HoursPerWeek = source.HoursPerWeek,
+                IsDisabilityConfident = source.IsDisabilityConfident,
+                IsNationalVacancy = source.VacancyLocationType != null && source.VacancyLocationType.Equals("National", StringComparison.CurrentCultureIgnoreCase),
+                NumberOfPositions = source.NumberOfPositions,
+                PostedDate = source.PostedDate,
+                ProviderName = source.ProviderName,
+                StartDate = source.StartDate,
+                Title = source.Title,
+                Ukprn = int.Parse(source.Ukprn),
+                VacancyReference = source.VacancyReference.Replace("VAC",""),
+                VacancyUrl = source.VacancyUrl,
+                Course = source,
+                Wage = source,
+                Distance = source.Distance,
+                Address = source,
+                EmployerWebsiteUrl = source.EmployerWebsiteUrl,
+                EmployerContactEmail = source.EmployerContactEmail,
+                EmployerContactName = source.EmployerContactName,
+                EmployerContactPhone = source.EmployerContactPhone,
+                ApprenticeshipLevel = source.ApprenticeshipLevel,
+                ExpectedDuration = source.ExpectedDuration,
+                Location = new VacancyLocation
+                {
+                    Lat = source.Location.Lat,
+                    Lon = source.Location.Lon
+                }
+            };
+        }
     }
 
     public class VacancyLocation
     {
+        /// <summary>
+        /// The latitude of the address where the apprentice will work.
+        /// </summary>
+        /// <example>51.500729</example>
         public double? Lat { get; set; }
+        /// <summary>
+        /// The longitude of the address where the apprentice will work.
+        /// </summary>
+        /// <example>-0.124625</example>
         public double? Lon { get; set; }
     }
 
+    /// <summary>
+    /// Will be either:
+    /// -	ApprenticeshipMinimum which is the National Minimum Wage for apprentices.
+    /// -	NationalMinimum which is the National Minimum Wage.
+    /// -	Custom which is a set salary set by the company.
+    /// -	CompetitiveSalary does not set an exact wage and shows the word ‘Competitive’.
+    /// </summary>
     public enum WageType
     {
         ApprenticeshipMinimum = 2,
         NationalMinimum = 3,
         Custom = 4,
         CompetitiveSalary = 6
     }
-    public enum WageUnit
-    {
-        Unspecified = 1,
-        Weekly = 2,
-        Monthly = 3,
-        Annually = 4
-    }
 }

src/Vacancies/SFA.DAS.Vacancies.Api/Models/GetVacancyAddressItem.cs

@@ -4,10 +4,25 @@ namespace SFA.DAS.Vacancies.Api.Models
 {
     public class GetVacancyAddressItem
     {
+        /// <summary>
+        /// First line of the address where the apprentice will work.
+        /// </summary>
         public string AddressLine1 { get; set; }
+        /// <summary>
+        /// Second line of the address where the apprentice will work.
+        /// </summary>
         public string AddressLine2 { get; set; }
+        /// <summary>
+        /// Third line of the address where the apprentice will work.
+        /// </summary>
         public string AddressLine3 { get; set; }
+        /// <summary>
+        /// Fourth line of the address where the apprentice will work.
+        /// </summary>
         public string AddressLine4 { get; set; }
+        /// <summary>
+        /// Postcode of the address where the apprentice will work.
+        /// </summary>
         public string Postcode { get; set; }
 
         public static implicit operator GetVacancyAddressItem(GetVacanciesListItem source)

src/Vacancies/SFA.DAS.Vacancies.Api/Models/GetVacancyCourseItem.cs

@@ -4,9 +4,24 @@ namespace SFA.DAS.Vacancies.Api.Models
 {
     public class GetVacancyCourseItem
     {
+        /// <summary>
+        /// The code from the learning aim reference service (LARS) for the apprenticeship’s training course (almost known as a ‘standard’). Use `GET list of courses` to see all courses and their LARS codes.
+        /// </summary>
         public int LarsCode { get; set; }
+        /// <summary>
+        /// The title of the apprenticeship training course and its level.
+        /// </summary>
+        /// <example>Furniture restorer (level 3)</example>
         public string Title { get; set; }
+        /// <summary>
+        /// What level the apprenticeship training course is.
+        /// </summary>
+        /// <example>3</example>
         public int Level { get; set; }
+        /// <summary>
+        /// Which route the apprenticeship training course is part of, using the routes from the Institute for Apprenticeships and Technical Education (IfATE). On Find an apprenticeship, we call these categories.
+        /// </summary>
+        /// <example>Creative and design</example>
         public string Route { get; set; }
         public static implicit operator GetVacancyCourseItem (GetVacanciesListItem source)
         {

src/Vacancies/SFA.DAS.Vacancies.Api/Models/GetVacancyResponse.cs

@@ -7,15 +7,27 @@ namespace SFA.DAS.Vacancies.Api.Models
 {
     public class GetVacancyResponse : GetVacanciesListResponseItem
     {
+        /// <summary>
+        /// A description of the company the apprentice will work at. Will be less than or equal to 4000 characters.
+        /// </summary>
+        public string EmployerDescription { get; set; }
+        /// <summary>
+        /// The apprenticeship�s training plan, including where and when training will take place.
+        /// </summary>
         public string TrainingDescription { get ; set ; }
-        public string FullDescription { get ; set ; }
+        /// <summary>
+        /// Additional information about the training, such as details about the provider.
+        /// </summary>
+        public string AdditionalTrainingDescription { get; set; }
+        /// <summary>
+        /// What progress or outcome the apprentice can expect at the end of the apprenticeship.
+        /// </summary>
         public string OutcomeDescription { get ; set ; }
-        public string EmployerDescription { get; set; }
+        public string FullDescription { get ; set ; }
         public List<string> Skills { get ; set ; }
         public List<GetVacancyQualification> Qualifications { get ; set ; }
         public string ThingsToConsider { get; set; }
         public string CompanyBenefitsInformation { get; set; }
-        public string AdditionalTrainingDescription { get; set; }
 
         public static implicit operator GetVacancyResponse(GetVacancyQueryResult source)
         {

src/Vacancies/SFA.DAS.Vacancies.Api/Models/GetVacancyWageItem.cs

@@ -4,13 +4,19 @@ namespace SFA.DAS.Vacancies.Api.Models
 {
     public class GetVacancyWageItem
     {
+        public WageType WageType { get; set; }
+        /// <summary>
+        /// If `wageType` is `Custom`, this will be the set annual wage for the apprenticeship.
+        /// </summary>
         public decimal? WageAmount { get; set; }
-        public decimal? WageAmountLowerBound { get; set; }
-        public decimal? WageAmountUpperBound { get; set; }
+        /// <summary>
+        /// Additional information about pay, such as when the apprentice might get a pay rise. Will be less than or equal to 250 characters.
+        /// </summary>
         public string WageAdditionalInformation { get; set; }
-        public WageType WageType { get; set; }
+        /// <summary>
+        /// Information about the working schedule, such as daily working hours. Will be less than or equal to 250 characters
+        /// </summary>
         public string WorkingWeekDescription { get; set; }
-        public WageUnit WageUnit { get; set; }
 
         public static implicit operator GetVacancyWageItem(GetVacanciesListItem source)
         {
@@ -19,10 +25,7 @@ public static implicit operator GetVacancyWageItem(GetVacanciesListItem source)
                 WageAmount = source.WageAmount,
                 WageType = source.WageType == 0 ? WageType.Custom : (WageType)source.WageType,
                 WageAdditionalInformation = source.WageText,
-                WorkingWeekDescription = source.WorkingWeek,
-                WageAmountLowerBound = source.WageAmountLowerBound,
-                WageAmountUpperBound = source.WageAmountUpperBound,
-                WageUnit = (WageUnit)source.WageUnit
+                WorkingWeekDescription = source.WorkingWeek
             };
         }
     }