0
# WADL Support
1

2
Web Application Description Language (WADL) generation and configuration for automatic API documentation. Provides machine-readable descriptions of RESTful web services including resources, methods, parameters, and representations.
3

4
## Capabilities
5

6
### WADL Application Context
7

8
Core WADL context providing access to WADL generation and configuration.
9

10
```java { .api }
11
/**
12
 * WADL application context providing access to WADL generation functionality.
13
 */
14
public interface WadlApplicationContext {
15
    
16
    /**
17
     * Get the WADL application representation.
18
     * @return WADL Application object
19
     */
20
    Application getApplication();
21
    
22
    /**
23
     * Get the WADL grammars section.
24
     * @return Grammars containing schema definitions
25
     */
26
    Grammars getGrammars();
27
    
28
    /**
29
     * Set whether WADL generation is enabled.
30
     * @param wadlGenerationEnabled true to enable WADL generation
31
     */
32
    void setWadlGenerationEnabled(boolean wadlGenerationEnabled);
33
    
34
    /**
35
     * Check if WADL generation is enabled.
36
     * @return true if WADL generation is enabled
37
     */
38
    boolean isWadlGenerationEnabled();
39
    
40
    /**
41
     * Get the WADL generator configuration.
42
     * @return WadlGeneratorConfig instance
43
     */
44
    WadlGeneratorConfig getWadlGeneratorConfig();
45
    
46
    /**
47
     * Set the WADL generator configuration.
48
     * @param wadlGeneratorConfig Configuration to set
49
     */
50
    void setWadlGeneratorConfig(WadlGeneratorConfig wadlGeneratorConfig);
51
}
52
```
53

54
### WADL Generator
55

56
Interface for generating WADL documents from Jersey resource models.
57

58
```java { .api }
59
/**
60
 * WADL generator interface for creating WADL documents.
61
 */
62
public interface WadlGenerator {
63
    
64
    /**
65
     * Initialize the WADL generator.
66
     */
67
    void init();
68
    
69
    /**
70
     * Create the root WADL application element.
71
     * @return WADL Application object
72
     */
73
    Application createApplication();
74
    
75
    /**
76
     * Create WADL resources element.
77
     * @return WADL Resources container
78
     */
79
    Resources createResources();
80
    
81
    /**
82
     * Create WADL resource element from Jersey resource.
83
     * @param resource Jersey Resource model
84
     * @param path Resource path
85
     * @return WADL Resource element
86
     */
87
    Resource createResource(org.glassfish.jersey.server.model.Resource resource, String path);
88
    
89
    /**
90
     * Create WADL method element from Jersey resource method.
91
     * @param resource Jersey Resource model
92
     * @param resourceMethod Jersey ResourceMethod model
93
     * @return WADL Method element
94
     */
95
    Method createMethod(org.glassfish.jersey.server.model.Resource resource, 
96
                       org.glassfish.jersey.server.model.ResourceMethod resourceMethod);
97
    
98
    /**
99
     * Create WADL request element.
100
     * @param resource Jersey Resource model
101
     * @param resourceMethod Jersey ResourceMethod model
102
     * @return WADL Request element
103
     */
104
    Request createRequest(org.glassfish.jersey.server.model.Resource resource,
105
                         org.glassfish.jersey.server.model.ResourceMethod resourceMethod);
106
    
107
    /**
108
     * Create WADL response element.
109
     * @param resource Jersey Resource model
110
     * @param resourceMethod Jersey ResourceMethod model
111
     * @return WADL Response element
112
     */
113
    Response createResponse(org.glassfish.jersey.server.model.Resource resource,
114
                           org.glassfish.jersey.server.model.ResourceMethod resourceMethod);
115
    
116
    /**
117
     * Create WADL parameter element.
118
     * @param resource Jersey Resource model
119
     * @param resourceMethod Jersey ResourceMethod model
120
     * @param parameter Jersey Parameter model
121
     * @return WADL Param element
122
     */
123
    Param createParam(org.glassfish.jersey.server.model.Resource resource,
124
                     org.glassfish.jersey.server.model.ResourceMethod resourceMethod,
125
                     org.glassfish.jersey.server.model.Parameter parameter);
126
    
127
    /**
128
     * Create WADL representation element.
129
     * @param resource Jersey Resource model
130
     * @param resourceMethod Jersey ResourceMethod model
131
     * @param mediaType Media type for the representation
132
     * @return WADL Representation element
133
     */
134
    Representation createRequestRepresentation(org.glassfish.jersey.server.model.Resource resource,
135
                                              org.glassfish.jersey.server.model.ResourceMethod resourceMethod,
136
                                              MediaType mediaType);
137
    
138
    /**
139
     * Create WADL response representation element.
140
     * @param resource Jersey Resource model
141
     * @param resourceMethod Jersey ResourceMethod model
142
     * @param mediaType Media type for the representation
143
     * @return WADL Representation element
144
     */
145
    Representation createResponseRepresentation(org.glassfish.jersey.server.model.Resource resource,
146
                                               org.glassfish.jersey.server.model.ResourceMethod resourceMethod,
147
                                               MediaType mediaType);
148
    
149
    /**
150
     * Get external grammars to include.
151
     * @return External grammars or null
152
     */
153
    ExternalGrammarDefinition createExternalGrammar();
154
    
155
    /**
156
     * Add any additional content to the WADL.
157
     * @param r Jersey Resource model
158
     * @param rm Jersey ResourceMethod model
159
     * @param existingItems Existing WADL items
160
     * @return Additional WADL elements to include
161
     */
162
    List<Object> createGenericResource(org.glassfish.jersey.server.model.Resource r,
163
                                      org.glassfish.jersey.server.model.ResourceMethod rm,
164
                                      List<Object> existingItems);
165
}
166
```
167

168
### WADL Feature
169

170
Jersey feature for enabling and configuring WADL support.
171

172
```java { .api }
173
/**
174
 * WADL feature for enabling WADL generation in Jersey applications.
175
 */
176
public class WadlFeature implements Feature {
177
    
178
    /**
179
     * Default constructor creating WADL feature with default configuration.
180
     */
181
    public WadlFeature();
182
    
183
    /**
184
     * Configure the feature in the given context.
185
     * @param context Feature context for configuration
186
     * @return true if feature was successfully configured
187
     */
188
    @Override
189
    public boolean configure(FeatureContext context);
190
    
191
    /**
192
     * Disable WADL generation.
193
     * @return WadlFeature with WADL generation disabled
194
     */
195
    public static WadlFeature disableWadl();
196
    
197
    /**
198
     * Enable WADL generation with default configuration.
199
     * @return WadlFeature with WADL generation enabled
200
     */
201
    public static WadlFeature enableWadl();
202
}
203
```
204

205
**Usage Examples:**
206

207
```java
208
import org.glassfish.jersey.server.wadl.WadlFeature;
209
import org.glassfish.jersey.server.ResourceConfig;
210
import org.glassfish.jersey.server.ServerProperties;
211

212
// Enable WADL in ResourceConfig
213
ResourceConfig config = new ResourceConfig()
214
    .packages("com.example.resources")
215
    .register(WadlFeature.class);
216

217
// Or enable WADL with specific configuration
218
ResourceConfig config2 = new ResourceConfig()
219
    .packages("com.example.resources")
220
    .register(WadlFeature.enableWadl());
221

222
// Disable WADL generation
223
ResourceConfig config3 = new ResourceConfig()
224
    .packages("com.example.resources")
225
    .register(WadlFeature.disableWadl());
226

227
// Configure WADL via properties
228
ResourceConfig config4 = new ResourceConfig()
229
    .packages("com.example.resources")
230
    .property(ServerProperties.WADL_FEATURE_DISABLE, false); // Enable WADL
231

232
// Access WADL at runtime
233
@Path("/application.wadl")
234
public class WadlResource {
235
    
236
    @Context
237
    private WadlApplicationContext wadlContext;
238
    
239
    @GET
240
    @Produces("application/xml")
241
    public Application getWadl() {
242
        return wadlContext.getApplication();
243
    }
244
}
245
```
246

247
### WADL Model Classes
248

249
Complete WADL model representation classes for building WADL documents.
250

251
```java { .api }
252
/**
253
 * WADL Application root element.
254
 */
255
public class Application {
256
    
257
    /**
258
     * Get the doc elements for documentation.
259
     * @return List of Doc elements
260
     */
261
    public List<Doc> getDoc();
262
    
263
    /**
264
     * Get the grammars section.
265
     * @return Grammars element
266
     */
267
    public Grammars getGrammars();
268
    
269
    /**
270
     * Set the grammars section.
271
     * @param value Grammars to set
272
     */
273
    public void setGrammars(Grammars value);
274
    
275
    /**
276
     * Get the resources collections.
277
     * @return List of Resources elements
278
     */
279
    public List<Resources> getResources();
280
    
281
    /**
282
     * Get resource types.
283
     * @return List of ResourceType elements
284
     */
285
    public List<ResourceType> getResourceType();
286
    
287
    /**
288
     * Get methods defined at application level.
289
     * @return List of Method elements
290
     */
291
    public List<Method> getMethod();
292
    
293
    /**
294
     * Get representations defined at application level.
295
     * @return List of Representation elements
296
     */
297
    public List<Representation> getRepresentation();
298
    
299
    /**
300
     * Get fault representations.
301
     * @return List of fault Representation elements
302
     */
303
    public List<Representation> getFault();
304
}
305

306
/**
307
 * WADL Resources collection element.
308
 */
309
public class Resources {
310
    
311
    /**
312
     * Get documentation elements.
313
     * @return List of Doc elements
314
     */
315
    public List<Doc> getDoc();
316
    
317
    /**
318
     * Get resource elements.
319
     * @return List of Resource elements
320
     */
321
    public List<Resource> getResource();
322
    
323
    /**
324
     * Get base URI for these resources.
325
     * @return Base URI string
326
     */
327
    public String getBase();
328
    
329
    /**
330
     * Set base URI for these resources.
331
     * @param value Base URI to set
332
     */
333
    public void setBase(String value);
334
}
335

336
/**
337
 * WADL Resource element representing a REST resource.
338
 */
339
public class Resource {
340
    
341
    /**
342
     * Get documentation elements.
343
     * @return List of Doc elements
344
     */
345
    public List<Doc> getDoc();
346
    
347
    /**
348
     * Get parameters for this resource.
349
     * @return List of Param elements
350
     */
351
    public List<Param> getParam();
352
    
353
    /**
354
     * Get methods available on this resource.
355
     * @return List of Method elements
356
     */
357
    public List<Method> getMethod();
358
    
359
    /**
360
     * Get sub-resources.
361
     * @return List of Resource elements
362
     */
363
    public List<Resource> getResource();
364
    
365
    /**
366
     * Get resource path.
367
     * @return Path string
368
     */
369
    public String getPath();
370
    
371
    /**
372
     * Set resource path.
373
     * @param value Path to set
374
     */
375
    public void setPath(String value);
376
    
377
    /**
378
     * Get resource ID.
379
     * @return Resource ID string
380
     */
381
    public String getId();
382
    
383
    /**
384
     * Set resource ID.
385
     * @param value ID to set
386
     */
387
    public void setId(String value);
388
    
389
    /**
390
     * Get resource type references.
391
     * @return List of resource type references
392
     */
393
    public List<String> getType();
394
}
395

396
/**
397
 * WADL Method element representing an HTTP method.
398
 */
399
public class Method {
400
    
401
    /**
402
     * Get documentation elements.
403
     * @return List of Doc elements
404
     */
405
    public List<Doc> getDoc();
406
    
407
    /**
408
     * Get request definition.
409
     * @return Request element
410
     */
411
    public Request getRequest();
412
    
413
    /**
414
     * Set request definition.
415
     * @param value Request to set
416
     */
417
    public void setRequest(Request value);
418
    
419
    /**
420
     * Get response definitions.
421
     * @return List of Response elements
422
     */
423
    public List<Response> getResponse();
424
    
425
    /**
426
     * Get HTTP method name.
427
     * @return HTTP method (GET, POST, etc.)
428
     */
429
    public String getName();
430
    
431
    /**
432
     * Set HTTP method name.
433
     * @param value Method name to set
434
     */
435
    public void setName(String value);
436
    
437
    /**
438
     * Get method ID.
439
     * @return Method ID string
440
     */
441
    public String getId();
442
    
443
    /**
444
     * Set method ID.
445
     * @param value ID to set
446
     */
447
    public void setId(String value);
448
}
449

450
/**
451
 * WADL Request element describing request structure.
452
 */
453
public class Request {
454
    
455
    /**
456
     * Get documentation elements.
457
     * @return List of Doc elements
458
     */
459
    public List<Doc> getDoc();
460
    
461
    /**
462
     * Get request parameters.
463
     * @return List of Param elements
464
     */
465
    public List<Param> getParam();
466
    
467
    /**
468
     * Get request representations.
469
     * @return List of Representation elements
470
     */
471
    public List<Representation> getRepresentation();
472
}
473

474
/**
475
 * WADL Response element describing response structure.
476
 */
477
public class Response {
478
    
479
    /**
480
     * Get documentation elements.
481
     * @return List of Doc elements
482
     */
483
    public List<Doc> getDoc();
484
    
485
    /**
486
     * Get response parameters.
487
     * @return List of Param elements
488
     */
489
    public List<Param> getParam();
490
    
491
    /**
492
     * Get response representations.
493
     * @return List of Representation elements
494
     */
495
    public List<Representation> getRepresentation();
496
    
497
    /**
498
     * Get fault representations.
499
     * @return List of fault Representation elements
500
     */
501
    public List<Representation> getFault();
502
    
503
    /**
504
     * Get HTTP status codes.
505
     * @return List of status codes
506
     */
507
    public List<Long> getStatus();
508
}
509

510
/**
511
 * WADL Param element describing parameters.
512
 */
513
public class Param {
514
    
515
    /**
516
     * Get documentation elements.
517
     * @return List of Doc elements
518
     */
519
    public List<Doc> getDoc();
520
    
521
    /**
522
     * Get parameter options.
523
     * @return List of Option elements
524
     */
525
    public List<Option> getOption();
526
    
527
    /**
528
     * Get link to parameter definition.
529
     * @return Link element
530
     */
531
    public Link getLink();
532
    
533
    /**
534
     * Set link to parameter definition.
535
     * @param value Link to set
536
     */
537
    public void setLink(Link value);
538
    
539
    /**
540
     * Get parameter name.
541
     * @return Parameter name
542
     */
543
    public String getName();
544
    
545
    /**
546
     * Set parameter name.
547
     * @param value Name to set
548
     */
549
    public void setName(String value);
550
    
551
    /**
552
     * Get parameter style.
553
     * @return ParamStyle enumeration value
554
     */
555
    public ParamStyle getStyle();
556
    
557
    /**
558
     * Set parameter style.
559
     * @param value ParamStyle to set
560
     */
561
    public void setStyle(ParamStyle value);
562
    
563
    /**
564
     * Get parameter type.
565
     * @return QName representing parameter type
566
     */
567
    public QName getType();
568
    
569
    /**
570
     * Set parameter type.
571
     * @param value Type to set
572
     */
573
    public void setType(QName value);
574
    
575
    /**
576
     * Get default value.
577
     * @return Default value string
578
     */
579
    public String getDefault();
580
    
581
    /**
582
     * Set default value.
583
     * @param value Default value to set
584
     */
585
    public void setDefault(String value);
586
    
587
    /**
588
     * Check if parameter is required.
589
     * @return true if required
590
     */
591
    public boolean isRequired();
592
    
593
    /**
594
     * Set whether parameter is required.
595
     * @param value true if required
596
     */
597
    public void setRequired(boolean value);
598
    
599
    /**
600
     * Check if parameter is repeating.
601
     * @return true if repeating
602
     */
603
    public boolean isRepeating();
604
    
605
    /**
606
     * Set whether parameter is repeating.
607
     * @param value true if repeating
608
     */
609
    public void setRepeating(boolean value);
610
}
611

612
/**
613
 * Parameter style enumeration.
614
 */
615
public enum ParamStyle {
616
    QUERY, HEADER, TEMPLATE, MATRIX, FORM, PLAIN
617
}
618

619
/**
620
 * WADL Representation element describing data representations.
621
 */
622
public class Representation {
623
    
624
    /**
625
     * Get documentation elements.
626
     * @return List of Doc elements
627
     */
628
    public List<Doc> getDoc();
629
    
630
    /**
631
     * Get representation parameters.
632
     * @return List of Param elements
633
     */
634
    public List<Param> getParam();
635
    
636
    /**
637
     * Get media type.
638
     * @return Media type string
639
     */
640
    public String getMediaType();
641
    
642
    /**
643
     * Set media type.
644
     * @param value Media type to set
645
     */
646
    public void setMediaType(String value);
647
    
648
    /**
649
     * Get element name.
650
     * @return QName of element
651
     */
652
    public QName getElement();
653
    
654
    /**
655
     * Set element name.
656
     * @param value Element QName to set
657
     */
658
    public void setElement(QName value);
659
    
660
    /**
661
     * Get profile URI.
662
     * @return Profile URI string
663
     */
664
    public String getProfile();
665
    
666
    /**
667
     * Set profile URI.
668
     * @param value Profile URI to set
669
     */
670
    public void setProfile(String value);
671
}
672
```
673

674
**Usage Examples:**
675

676
```java
677
import com.sun.research.ws.wadl.*;
678
import org.glassfish.jersey.server.wadl.WadlGenerator;
679

680
// Custom WADL generator implementation
681
public class CustomWadlGenerator implements WadlGenerator {
682
    
683
    @Override
684
    public void init() {
685
        // Initialize generator
686
    }
687
    
688
    @Override
689
    public Application createApplication() {
690
        Application app = new Application();
691
        
692
        // Add application-level documentation
693
        Doc doc = new Doc();
694
        doc.setTitle("My REST API");
695
        doc.getContent().add("This is a comprehensive REST API for managing resources.");
696
        app.getDoc().add(doc);
697
        
698
        return app;
699
    }
700
    
701
    @Override
702
    public Resources createResources() {
703
        Resources resources = new Resources();
704
        resources.setBase("http://localhost:8080/api");
705
        
706
        // Add resources documentation
707
        Doc doc = new Doc();
708
        doc.setTitle("API Resources");
709
        doc.getContent().add("Collection of all available API resources.");
710
        resources.getDoc().add(doc);
711
        
712
        return resources;
713
    }
714
    
715
    @Override
716
    public Resource createResource(org.glassfish.jersey.server.model.Resource resource, String path) {
717
        Resource wadlResource = new Resource();
718
        wadlResource.setPath(path);
719
        wadlResource.setId(generateResourceId(resource));
720
        
721
        // Add resource documentation
722
        Doc doc = new Doc();
723
        doc.setTitle("Resource: " + path);
724
        doc.getContent().add("Operations available on " + path);
725
        wadlResource.getDoc().add(doc);
726
        
727
        return wadlResource;
728
    }
729
    
730
    @Override
731
    public Method createMethod(org.glassfish.jersey.server.model.Resource resource,
732
                              org.glassfish.jersey.server.model.ResourceMethod resourceMethod) {
733
        Method wadlMethod = new Method();
734
        wadlMethod.setName(resourceMethod.getHttpMethod());
735
        wadlMethod.setId(generateMethodId(resourceMethod));
736
        
737
        // Add method documentation
738
        Doc doc = new Doc();
739
        doc.setTitle(resourceMethod.getHttpMethod() + " " + resource.getPath());
740
        doc.getContent().add("Performs " + resourceMethod.getHttpMethod() + " operation");
741
        wadlMethod.getDoc().add(doc);
742
        
743
        return wadlMethod;
744
    }
745
    
746
    @Override
747
    public Request createRequest(org.glassfish.jersey.server.model.Resource resource,
748
                               org.glassfish.jersey.server.model.ResourceMethod resourceMethod) {
749
        Request request = new Request();
750
        
751
        // Add parameters
752
        for (org.glassfish.jersey.server.model.Parameter param : resourceMethod.getInvocable().getParameters()) {
753
            Param wadlParam = createParam(resource, resourceMethod, param);
754
            request.getParam().add(wadlParam);
755
        }
756
        
757
        return request;
758
    }
759
    
760
    @Override
761
    public Param createParam(org.glassfish.jersey.server.model.Resource resource,
762
                           org.glassfish.jersey.server.model.ResourceMethod resourceMethod,
763
                           org.glassfish.jersey.server.model.Parameter parameter) {
764
        Param wadlParam = new Param();
765
        wadlParam.setName(parameter.getSourceName());
766
        wadlParam.setRequired(!parameter.hasDefaultValue());
767
        
768
        // Set parameter style based on source
769
        switch (parameter.getSource()) {
770
            case PATH:
771
                wadlParam.setStyle(ParamStyle.TEMPLATE);
772
                break;
773
            case QUERY:
774
                wadlParam.setStyle(ParamStyle.QUERY);
775
                break;
776
            case HEADER:
777
                wadlParam.setStyle(ParamStyle.HEADER);
778
                break;
779
            case FORM:
780
                wadlParam.setStyle(ParamStyle.FORM);
781
                break;
782
            default:
783
                wadlParam.setStyle(ParamStyle.PLAIN);
784
        }
785
        
786
        // Set default value if available
787
        if (parameter.hasDefaultValue()) {
788
            wadlParam.setDefault(parameter.getDefaultValue());
789
        }
790
        
791
        return wadlParam;
792
    }
793
    
794
    // Additional method implementations...
795
    
796
    private String generateResourceId(org.glassfish.jersey.server.model.Resource resource) {
797
        return "resource_" + resource.getPath().replaceAll("[^a-zA-Z0-9]", "_");
798
    }
799
    
800
    private String generateMethodId(org.glassfish.jersey.server.model.ResourceMethod method) {
801
        return method.getHttpMethod().toLowerCase() + "_" + method.getInvocable().getHandlingMethod().getName();
802
    }
803
}
804

805
// Register custom WADL generator
806
ResourceConfig config = new ResourceConfig()
807
    .packages("com.example.resources")
808
    .register(WadlFeature.class)
809
    .property(ServerProperties.WADL_GENERATOR_CONFIG, CustomWadlGenerator.class.getName());
810
```