כתיבה והוספת הערות לקוד

בדף הזה מוסבר איך לבנות את הקוד של Cloud Endpoints Frameworks ולהוסיף לו הערות. רשימה מלאה של כל ההערות הנתמכות מופיעה במאמר בנושא הערות.

לפני שמתחילים

1. הגדרת סביבת הפיתוח.

2. משכפלים את הדוגמה של Endpoints Frameworks:

    git clone https://github.com/GoogleCloudPlatform/java-docs-samples.git
   

3. דוגמה למסגרת Endpoints Frameworks נמצאת במיקום:

    cd appengine-java8/endpoints-v2-skeleton/
   

כדי להסביר איך הערות פועלות, במסמך הזה נעשה שימוש בדוגמה endpoints-v2-backend כדי להציג את ההערות וקוד אחר שצריך להוסיף לדוגמה endpoints-v2-skeleton כדי שהיא תורכב. בסופו של דבר, דוגמת endpoints-v2-skeleton שעברה שינוי מתנהגת כמו דוגמת endpoints-v2-backend, שמשמשת במאמר Getting started with Endpoints Frameworks on App Engine.

יצירה של קוד והוספת הערות לקוד

כדי להוסיף הערות לקוד:

1. משנים את הספריות לספריית קובצי המקור של Java בפרויקט, לדוגמה: src/main/java/com/example/skeleton.
2. יוצרים קובץ מחלקה של JavaBean בשם Message.java שמכיל את הקוד הבא:
   public class Message {
   
     private String message;
   
     public String getMessage() {
       return this.message;
     }
   
     public void setMessage(String message) {
       this.message = message;
     }
   }

3. עורכים את הקובץ MyApi.java שכלול בדוגמה של השלד. מחליפים את הערת ההגדרה @Api בהערה הבאה:
   @Api(
       name = "echo",
       version = "v1",
       namespace =
       @ApiNamespace(
           ownerDomain = "echo.example.com",
           ownerName = "echo.example.com",
           packagePath = ""
       ),
       // ...
   )

   המאפיין version = "v1" מציין את הגרסה של ה-API לדוגמה. הערך שאתם מזינים הופך לחלק מהנתיב בכתובת ה-URL של ה-API. מידע נוסף על גרסאות זמין במאמר טיפול בגרסאות של API.

4. מוסיפים את שיטת echo כנקודת קצה ל-API הראשונה ואת שיטת העזר doEcho ל-MyApi.java.
   @ApiMethod(name = "echo")
   public Message echo(Message message, @Named("n") @Nullable Integer n) {
     return doEcho(message, n);
   }

   private Message doEcho(Message request, Integer n) {
     Message response = new Message();
     if (n != null && n >= 0) {
       StringBuilder sb = new StringBuilder();
       for (int i = 0; i < n; i++) {
         if (i > 0) {
           sb.append(' ');
         }
         sb.append(request.getMessage());
       }
       response.setMessage(sb.toString());
     }
     return response;
   }

5. מעתיקים את כל הייבוא מ- Echo.java ומדביקים אותו ב-MyApi.java.

6. Maven

   מבצעים build של הפרויקט:

   mvn clean package

   Gradle

   מבצעים build של הפרויקט:

   gradle clean build

הערות – מידע בסיסי

יש שלוש הערות שמשמשות בדרך כלל בממשקי API של קצה עורפי:

• ‫@Api מכיל את פרטי ההגדרה של ה-API של הקצה העורפי.
• ‫@ApiMethod מציין שיטה של מחלקה ששייכת ל-API של הקצה העורפי. שיטות שלא מסומנות ב-@ApiMethod לא נכללות כשיוצרים ספריות לקוח ומסמכי גילוי. אפשר להשתמש בהערה @ApiMethod גם כדי לבטל את הגדרת ה-API עבור שיטה ספציפית.
• צריך להוסיף את @Named לכל הפרמטרים שמועברים לשיטות בצד השרת, אלא אם הפרמטר הוא מסוג ישות.

רשימה מלאה של כל ההערות של Endpoints Frameworks מופיעה במאמר בנושא הערות ותחביר.

המאמרים הבאים

• מידע נוסף על הוספת ניהול API
• מידע נוסף על הפרמטרים וסוגי ההחזרה הנתמכים
• מידע נוסף על חריגים וקודי סטטוס