Skip to content

Commit adf5c1f

Browse files
fehguyfehguy
committed
updated snapshot build, merged per #722 (comment) 
1 parent b247904 commit adf5c1f

File tree

109 files changed

+3449
-1628
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

109 files changed

+3449
-1628
lines changed

‎README.md‎

Lines changed: 12 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22

33
[![Build Status](https://travis-ci.org/wordnik/swagger-core.png)](https://travis-ci.org/wordnik/swagger-core)
44

5-
The goal of Swagger™ is to define a standard, language-agnostic interface to REST APIs which allows both humans and computers to discover and understand the capabilities of the service without access to source code, documentation, or through network traffic inspection. When properly defined via Swagger, a consumer can understand and interact with the remote service with a minimal amount of implementation logic. Similar to what interfaces have done for lower-level programming, Swager removes the guesswork in calling the service.
5+
The goal of Swagger™ is to define a standard, language-agnostic interface to REST APIs which allows both humans and computers to discover and understand the capabilities of the service without access to source code, documentation, or through network traffic inspection. When properly defined via Swagger, a consumer can understand and interact with the remote service with a minimal amount of implementation logic. Similar to what interfaces have done for lower-level programming, Swagger removes the guesswork in calling the service.
66

77
Swagger-core is the Java/Scala implementation of Swagger. It supports *JAX-RS*, *plain Servlets*, and *Play Framework*.
88

@@ -22,6 +22,15 @@ The following methods are available to obtain support for Swagger:
2222
## Get started with Swagger!
2323
See the guide on [getting started with swagger](https://github.com/wordnik/swagger-core/wiki/Adding-Swagger-to-your-API) to get started with adding swagger to your API.
2424

25+
## Compatability
26+
The Swagger Specification has undergone 3 revisions since initial creation in 2010. The swagger-core project has the following compatibilies with the swagger specification:
27+
28+
Swagger core Version | Release Date | Swagger Spec compatability | Notes | Status
29+
------------------------- | ------------ | -------------------------- | ----- | ----
30+
1.5.0 (in development) | n/a | 2.0 | [branch develop_2.0](https://github.com/wordnik/swagger-core/tree/develop_2.0) | [1.5.0 Milestone](https://github.com/wordnik/swagger-core/milestones/v1.5.0)
31+
1.3.10 | 2014-09-18 | 1.2 | [tag v1.3.10](https://github.com/wordnik/swagger-core/tree/v1.3.10)
32+
1.2.4 | 2013-06-19 | 1.1 | [tag swagger-project_2.10.0-1.2.4](https://github.com/wordnik/swagger-core/tree/swagger-project_2.10.0-1.2.4)
33+
1.0.0 | 2011-10-16 | 1.0 | [tag v1.0](https://github.com/wordnik/swagger-core/tree/v1.0)
2534

2635
## Overview
2736
This is a project to build the swagger-core library, which is required for the Wordnik
@@ -36,11 +45,11 @@ If you're interested in the change history of swagger and the swagger-core frame
3645
### Prerequisites
3746
You need the following installed and available in your $PATH:
3847

39-
<li>- Java 1.6 or greater (http://java.oracle.com)
48+
<li>- Java 6, 7 (http://java.oracle.com)
4049

4150
<li>- Apache maven 3.0.4 or greater (http://maven.apache.org/)
4251

43-
### To build from source (currently 1.3.5)
52+
### To build from source (currently 1.3.10)
4453
```
4554
# first time building locally
4655
mvn -N

‎modules/swagger-annotations/pom.xml‎

Lines changed: 2 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -3,20 +3,19 @@
33
<parent>
44
<groupId>com.wordnik</groupId>
55
<artifactId>swagger-project_2.10</artifactId>
6-
<version>1.3.8-SNAPSHOT</version>
6+
<version>1.3.11-SNAPSHOT</version>
77
<relativePath>../..</relativePath>
88
</parent>
99
<modelVersion>4.0.0</modelVersion>
1010
<groupId>com.wordnik</groupId>
1111
<artifactId>swagger-annotations</artifactId>
12-
<version>1.3.8-SNAPSHOT</version>
12+
<version>1.3.11-SNAPSHOT</version>
1313
<packaging>bundle</packaging>
1414
<name>swagger-annotations</name>
1515

1616
<build>
1717
<sourceDirectory>src/main/java</sourceDirectory>
1818
<defaultGoal>install</defaultGoal>
19-
2019
<plugins>
2120
<plugin>
2221
<groupId>org.apache.felix</groupId>
@@ -29,6 +28,5 @@
2928
</configuration>
3029
</plugin>
3130
</plugins>
32-
3331
</build>
3432
</project>

‎modules/swagger-annotations/src/main/java/com/wordnik/swagger/annotations/Api.java‎

Lines changed: 87 additions & 26 deletions
Original file line numberDiff line numberDiff line change
@@ -16,43 +16,104 @@
1616

1717
package com.wordnik.swagger.annotations;
1818

19-
import java.lang.annotation.ElementType;
20-
import java.lang.annotation.Retention;
21-
import java.lang.annotation.RetentionPolicy;
22-
import java.lang.annotation.Target;
19+
import java.lang.annotation.*;
2320

2421

2522
/**
26-
* describes a top-level api. Classes with @Api annotations will
27-
* be included in the Resource Listing: https://github.com/wordnik/swagger-core/wiki/Resource-Listing
28-
* for details
23+
* Marks a class as a Swagger resource.
24+
* <p/>
25+
* The resource affects both the root document of Swagger, the Resource
26+
* Listing, and the API Declaration of that specific resource.
27+
* <p/>
28+
* Swagger will only include and introspect only classes that are annotated
29+
* with {@code @Api} and will ignore other resources (JAX-RS endpoints, Servlets and
30+
* so on).
2931
*/
3032
@Target(ElementType.TYPE)
3133
@Retention(RetentionPolicy.RUNTIME)
34+
@Inherited
3235
public @interface Api {
33-
/** Short description of the Api */
34-
String value();
36+
/**
37+
* The 'path' that is going to be used to host the API Declaration of the
38+
* resource.
39+
* <p/>
40+
* For JAX-RS resources, this would normally have the same value as the {@code @Path}
41+
* on the resource, but can be any other value as well. It will serve as the path
42+
* where the documentation is hosted.
43+
* <p/>
44+
* For Servlets, this path has to be the path serving the Servlet.
45+
* <p/>
46+
* If the value isn't preceded with a slash, one would be added to it.
47+
*/
48+
String value();
3549

36-
/** General description of this class */
37-
String description() default "";
50+
/**
51+
* Corresponds to the `description` field of the Resource Listing API operation.
52+
* <p/>
53+
* This should be a short description of the resource.
54+
*/
55+
String description() default "";
3856

39-
/** The base path that is prepended to all @Path elements. This may be an override for certain scenarios only */
40-
String basePath() default "";
41-
42-
/** optional explicit ordering of this Api in the Resource Listing */
43-
int position() default 0;
57+
/**
58+
* Corresponds to the `basePath` field of the API Declaration.
59+
* <p/>
60+
* The `basePath` is derived automatically by Swagger. This property allows
61+
* overriding the default value if needed.
62+
*
63+
* @since 1.3.7
64+
*/
65+
String basePath() default "";
4466

45-
/** content type produced by this Api */
46-
String produces() default "";
67+
/**
68+
* Optional explicit ordering of this API resource in the Resource Listing.
69+
*/
70+
int position() default 0;
4771

48-
/** media type consumed by this Api */
49-
String consumes() default "";
72+
/**
73+
* Corresponds to the `produces` field of the API Declaration.
74+
* <p/>
75+
* Takes in comma-separated values of content types.
76+
* For example, "application/json, application/xml" would suggest this API Resource
77+
* generates JSON and XML output.
78+
* <p/>
79+
* For JAX-RS resources, this would automatically take the value of the {@code @Produces}
80+
* annotation if such exists. It can also be used to override the {@code @Produces} values
81+
* for the Swagger documentation.
82+
*/
83+
String produces() default "";
5084

51-
/** protocols that this Api requires (i.e. https) */
52-
String protocols() default "";
85+
/**
86+
* Corresponds to the `consumes` field of the API Declaration.
87+
* <p/>
88+
* Takes in comma-separated values of content types.
89+
* For example, "application/json, application/xml" would suggest this API Resource
90+
* accepts JSON and XML input.
91+
* <p/>
92+
* For JAX-RS resources, this would automatically take the value of the {@code @Consumes}
93+
* annotation if such exists. It can also be used to override the {@code @Consumes} values
94+
* for the Swagger documentation.
95+
*/
96+
String consumes() default "";
5397

54-
/** authorizations required by this Api */
55-
// String authorizations() default "";
56-
/** authorizations required by this Api */
57-
Authorization[] authorizations() default @Authorization("");
98+
/**
99+
* This property is currently not in use.
100+
*/
101+
String protocols() default "";
102+
103+
/**
104+
* Corresponds to the `authorizations` field of the API Declaration.
105+
* <p/>
106+
* Takes in a list of the required authorizations for this API Resource.
107+
* This may be overridden by specific operations.
108+
*
109+
* @see Authorization
110+
*/
111+
Authorization[] authorizations() default @Authorization("");
112+
113+
/**
114+
* Hides the api.
115+
*
116+
* @since 1.3.8
117+
*/
118+
boolean hidden() default false;
58119
}

‎modules/swagger-annotations/src/main/java/com/wordnik/swagger/annotations/ApiImplicitParam.java‎

Lines changed: 77 additions & 29 deletions
Original file line numberDiff line numberDiff line change
@@ -16,47 +16,95 @@
1616

1717
package com.wordnik.swagger.annotations;
1818

19-
import java.lang.annotation.ElementType;
20-
import java.lang.annotation.Retention;
21-
import java.lang.annotation.RetentionPolicy;
22-
import java.lang.annotation.Target;
19+
import java.lang.annotation.*;
2320

2421
/**
25-
* Represents a single parameter in an Api Operation. A parameter is an input
26-
* to the operation. The difference with the ApiImplicitParam is that they are
27-
* not bound to a variable, and allow for more manually-defined descriptions.
22+
* Represents a single parameter in an API Operation.
23+
* <p/>
24+
* While {@link com.wordnik.swagger.annotations.ApiParam} is bound to a JAX-RS parameter,
25+
* method or field, this allows you to manually define a parameter in a fine-tuned manner.
26+
* This is the only way to define parameters when using Servlets or other non-JAX-RS
27+
* environments.
28+
* <p/>
29+
* This annotation must be used as a value of {@link com.wordnik.swagger.annotations.ApiImplicitParams}
30+
* in order to be parsed.
31+
*
32+
* @see com.wordnik.swagger.annotations.ApiImplicitParams
2833
*/
2934
@Target(ElementType.METHOD)
3035
@Retention(RetentionPolicy.RUNTIME)
36+
@Inherited
3137
public @interface ApiImplicitParam {
32-
/** Name of the parameter */
33-
String name() default "";
38+
/**
39+
* Name of the parameter.
40+
* <p/>
41+
* For proper Swagger functionality, follow these rules when naming your parameters based on {@link #paramType()}:
42+
* <ol>
43+
* <li>If {@code paramType} is "path", the name should be the associated section in the path.</li>
44+
* <li>If {@code paramType} is "body", the name should be "body".</li>
45+
* <li>For all other cases, the name should be the parameter name as your application expects to accept.</li>
46+
* </ol>
47+
*
48+
* @see #paramType()
49+
*/
50+
String name() default "";
3451

35-
/** Description of the parameter */
36-
String value() default "";
52+
/**
53+
* A brief description of the parameter.
54+
*/
55+
String value() default "";
3756

38-
/** Default value - if e.g. no JAX-RS @DefaultValue is given */
39-
String defaultValue() default "";
57+
/**
58+
* Describes the default value for the parameter.
59+
*/
60+
String defaultValue() default "";
4061

41-
/** Description of values this endpoint accepts */
42-
String allowableValues() default "";
62+
/**
63+
* Limits the acceptable values for this parameter.
64+
* <p/>
65+
* There are three ways to describe the allowable values:
66+
* <ol>
67+
* <li>To set a list of values, provide a comma-separated list surrounded by square brackets.
68+
* For example: {@code [first, second, third]}.</li>
69+
* <li>To set a range of values, start the value with "range", and surrounding by square
70+
* brackets include the minimum and maximum values. For example: {@code range[1, 5]}.</li>
71+
* <li>To set a minimum/maximum value, use the same format for range but use "infinity"
72+
* or "-infinity" as the second value. For example, {@code range[1, infinity]} means the
73+
* minimum allowable value of this parameter is 1.</li>
74+
* </ol>
75+
*/
76+
String allowableValues() default "";
4377

44-
/** specifies if the parameter is required or not */
45-
boolean required() default false;
78+
/**
79+
* Specifies if the parameter is required or not.
80+
* <p/>
81+
* Path parameters should always be set as required.
82+
*/
83+
boolean required() default false;
4684

47-
/**
48-
* specify an optional access value for filtering in a Filter
49-
* implementation. This
50-
* allows you to hide certain parameters if a user doesn't have access to them
51-
*/
52-
String access() default "";
85+
/**
86+
* Allows for filtering a parameter from the API documentation.
87+
*
88+
* @see com.wordnik.swagger.core.filter.SwaggerSpecFilter
89+
*/
90+
String access() default "";
5391

54-
/** specifies whether or not the parameter can have multiple values provided */
55-
boolean allowMultiple() default false;
92+
/**
93+
* Specifies whether the parameter can accept multiple comma-separated values.
94+
*/
95+
boolean allowMultiple() default false;
5696

57-
/** manually set the dataType */
58-
String dataType() default "";
97+
/**
98+
* The data type of the parameter.
99+
* <p/>
100+
* This can be the class name or a primitive.
101+
*/
102+
String dataType() default "";
59103

60-
/** manually set the param type, i.e. query, path, etc. */
61-
String paramType() default "";
104+
/**
105+
* The parameter type of the parameter.
106+
*
107+
* Valid values are {@code path}, {@code query}, {@code body}, {@code header} or {@code form}.
108+
*/
109+
String paramType() default "";
62110
}

‎modules/swagger-annotations/src/main/java/com/wordnik/swagger/annotations/ApiImplicitParams.java‎

Lines changed: 9 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -16,16 +16,19 @@
1616

1717
package com.wordnik.swagger.annotations;
1818

19-
import java.lang.annotation.ElementType;
20-
import java.lang.annotation.Retention;
21-
import java.lang.annotation.RetentionPolicy;
22-
import java.lang.annotation.Target;
19+
import java.lang.annotation.*;
2320

2421
/**
25-
* A simple array wrapper to contain multiple ApiImplicitParam objects
22+
* A wrapper to allow a list of multiple {@link com.wordnik.swagger.annotations.ApiImplicitParam} objects.
23+
*
24+
* @see com.wordnik.swagger.annotations.ApiImplicitParam
2625
*/
2726
@Target(ElementType.METHOD)
2827
@Retention(RetentionPolicy.RUNTIME)
28+
@Inherited
2929
public @interface ApiImplicitParams {
30-
ApiImplicitParam[] value();
30+
/**
31+
* A list of {@link com.wordnik.swagger.annotations.ApiImplicitParam}s available to the API operation.
32+
*/
33+
ApiImplicitParam[] value();
3134
}

0 commit comments

Comments
 (0)