swagger
अकड़-ui

टिप्पणियों

जर्सी बाकी WS के साथ स्वैगर-उई

जैसा कि स्वैगर की आधिकारिक वेबसाइट कहती है:

स्वैगर REST एपीआई के लिए एक मानक, भाषा-अज्ञेय इंटरफ़ेस को परिभाषित करने के लिए है जो मानव और कंप्यूटर दोनों को स्रोत कोड, प्रलेखन या नेटवर्क ट्रैफिक निरीक्षण के माध्यम से सेवा की क्षमताओं को खोजने और समझने की अनुमति देता है। जब स्वैगर के माध्यम से ठीक से परिभाषित किया जाता है, तो एक उपभोक्ता न्यूनतम तर्क कार्यान्वयन के साथ दूरस्थ सेवा के साथ समझ और बातचीत कर सकता है। निचले स्तर की प्रोग्रामिंग के लिए इंटरफेस ने जो किया है, उसके समान, स्वैगर सेवा को कॉल करने में अनुमान को हटा देता है।

मान लें कि आप मावेन और जर्सी का उपयोग करते हैं, तो आपको जुड़ने के लिए निम्न निर्भरता की आवश्यकता होगी: जेवेन-आरएस की निर्भरता के साथ मावेन स्वैगर निर्भरता । अब आपको "maven webapp" बनाना होगा और webapp के तहत आपको इस URL पर मौजूद सामग्री को पेस्ट करना होगा । आपके प्रोजेक्ट में उन सामग्रियों को चिपकाने के बाद वेबएप की फ़ोल्डर संरचना निम्न प्रकार दिखनी चाहिए:

उसके बाद इस चरण का पालन करें:

1. किसी भी नाम के साथ एक जावा फ़ाइल बनाएँ (हमारे मामले में इसका " ApiOriginFilter.java ") नीचे के समान:

import javax.servlet.FilterChain;
import javax.servlet.FilterConfig;
import javax.servlet.ServletException;

import javax.servlet.ServletRequest;
import javax.servlet.ServletResponse;
import javax.servlet.http.HttpServletResponse;
import java.io.IOException;

public class ApiOriginFilter implements javax.servlet.Filter {
    /**
     * doFilter
     */
    @Override
    public void doFilter(ServletRequest request, ServletResponse response, FilterChain chain)
            throws IOException, ServletException {
        HttpServletResponse res = (HttpServletResponse) response;
        res.addHeader("Access-Control-Allow-Origin", "*");
        res.addHeader("Access-Control-Allow-Methods", "GET, POST, DELETE, PUT");
        res.addHeader("Access-Control-Allow-Headers", "Content-Type, api_key, Authorization");
        chain.doFilter(request, response);
    }

    /**
     * destroy
     */
    @Override
    public void destroy() {
    }

    /**
     * init
     */
    @Override
    public void init(FilterConfig filterConfig) throws ServletException {
    }
}

यह फ़ाइल आने वाले अनुरोधों को फ़िल्टर करना सुनिश्चित करेगी जैसा कि कक्षा में प्रदान किया गया है।

2. हमारे मामले में किसी भी नाम मान लीजिए की एक जावा फ़ाइल बनाएँ, इसका नाम " SwaggerJaxrsConfig.java " है:

import org.eclipse.persistence.jaxb.MarshallerProperties;
import org.eclipse.persistence.jaxb.BeanValidationMode;
import org.glassfish.jersey.moxy.json.MoxyJsonConfig;
import org.glassfish.jersey.moxy.json.MoxyJsonFeature;
import org.glassfish.jersey.moxy.xml.MoxyXmlFeature;
import org.glassfish.jersey.server.ResourceConfig;

import org.glassfish.jersey.server.ServerProperties;
import org.glassfish.jersey.server.filter.RolesAllowedDynamicFeature;
import io.swagger.jaxrs.config.BeanConfig;

public class SwaggerJaxrsConfig extends ResourceConfig {

public SwaggerJaxrsConfig() {
    BeanConfig beanConfig = new BeanConfig();
    beanConfig.setTitle("Swagger API Title");
    beanConfig.setVersion("1.0.0");        
    beanConfig.setSchemes(new String[] { "http" });
    beanConfig.setHost("localhost:8080/swagger-ui");
    beanConfig.setBasePath("/rest");
    beanConfig.setResourcePackage(
            "your.restws.package");
    beanConfig.setScan(true);        
    property(ServerProperties.BV_SEND_ERROR_IN_RESPONSE, Boolean.TRUE);
    packages("your.restws.package");
    packages("io.swagger.jaxrs.listing");
    register(MoxyJsonFeature.class);
    // register(BadRequestExceptionMapper.class);
    register(new MoxyJsonConfig().setFormattedOutput(true)
    // Turn off BV otherwise the entities on server would be validated by MOXy as well.
    .property(MarshallerProperties.BEAN_VALIDATION_MODE, BeanValidationMode.NONE).resolver());

    register(MoxyXmlFeature.class);
    register(RolesAllowedDynamicFeature.class);
}
}

जैसा कि आप देख सकते हैं, ऊपर की कक्षा में हमने होस्ट की तरह स्वैगर UI का उपयोग करने के लिए आवश्यक सभी विवरण प्रदान किए हैं, जिस पर इस स्वैगर परियोजना को आपकी पसंद का आधार पथ सेट करने की सुविधा के साथ होस्ट किया जाएगा और सभी http प्रोटोकॉल जैसे " http " या " https " और यहां तक कि आपकी आवश्यकता के अनुसार और भी अधिक विवरण। जहाँ स्वैगर को आपके REST WS के सभी स्थान के बारे में बताने का भी प्रावधान है, जो संकुल के साथ-साथ setResourcePackage का उपयोग करके सेट किया जा सकता है। यह वर्ग हमें अपने अनुकूलन के साथ Swagger UI का उपयोग करने में सक्षम बनाता है।

अब Web.xml में उपरोक्त 2 फाइलों की प्रविष्टि करें ताकि हमारे एप्लिकेशन को सर्वर पर लागू करने के बाद उनका उपयोग करें जैसे कि निम्नलिखित:

<servlet>
    <servlet-name>jersey-servlet</servlet-name>
    <servlet-class>org.glassfish.jersey.servlet.ServletContainer</servlet-class>
    <init-param>
        <param-name>javax.ws.rs.Application</param-name>
        <param-value>your.package.SwaggerJaxrsConfig</param-value>
    </init-param>
    <load-on-startup>1</load-on-startup>
</servlet>
<servlet-mapping>
    <servlet-name>jersey-servlet</servlet-name>
    <url-pattern>/rest/*</url-pattern>
</servlet-mapping>

<filter>
    <filter-name>ApiOriginFilter</filter-name>
    <filter-class>your.package.ApiOriginFilter</filter-class>
</filter>
<filter-mapping>
    <filter-name>ApiOriginFilter</filter-name>
    <url-pattern>/rest/*</url-pattern>
</filter-mapping>

अब, हम वास्तविक कोड पर जाएँगे जहाँ हम स्वैगर प्रदान किए गए एनोटेशन का उपयोग करेंगे:

नीचे के रूप में एक सेम कर्मचारी बनाएं।

import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;

@ApiModel("Employee bean")
public class Employee {

    private String name;
    private String id;
    private String dept;

    @ApiModelProperty(value = "Name of employee", example = "Test Employee")
    public String getName() {
        return name;
    }

    public void setName(String name) {
        this.name = name;
    }

    @ApiModelProperty(value = "Id of employee", example = "123456")
    public String getId() {
        return id;
    }

    public void setId(String id) {
        this.id = id;
    }

    @ApiModelProperty(value = "Department of employee", example = "IT Division", allowableValues = "IT, Sales, Admin")
    public String getDept() {
        return dept;
    }

    public void setDept(String dept) {
        this.dept = dept;
    }
}

स्वैगर के घटक जिनका हम यहां उपयोग करते हैं वे हैं:

1. @ApiModel("Employee bean") - यह बीन वर्ग का नाम तय करेगा जिसे स्वैगर यूआई पर प्रदर्शित करने की आवश्यकता है।
2. @ApiModelProperty(value ="ABC", example="DeptName") - यह सेम में प्रयुक्त प्रत्येक क्षेत्र की जानकारी प्रदान करेगा। मान क्षेत्र का विवरण प्रदान करता है और उदाहरण उस क्षेत्र का नमूना मूल्य प्रदान करता है।

अब हम एक REST कंट्रोलर बनाएंगे जो निम्नानुसार एक GET वेबसर्विस बनाने के लिए है:

import javax.ws.rs.GET;
import javax.ws.rs.Path;
import javax.ws.rs.Produces;
import javax.ws.rs.core.GenericEntity;
import javax.ws.rs.core.MediaType;
import javax.ws.rs.core.Response;

import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.swagger.ws.bean.Employee;
import org.swagger.ws.service.EmployeeService;

import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import io.swagger.annotations.ApiResponse;
import io.swagger.annotations.ApiResponses;

@Path("/employee")
@Api(tags = {"Employee"})
public class EmployeeController {
    private static final Logger LOGGER = LoggerFactory.getLogger(EmployeeController.class);

@GET
@Produces(MediaType.APPLICATION_JSON + ";charset=utf-8")
@ApiOperation(produces="application/json", value = "Fetch employee details", httpMethod="GET", notes = "<br>This service fetches Employee details", response = Employee.class)
@ApiResponses(value = { @ApiResponse(code = 200,response = Employee.class, message = "Successful operation"),@ApiResponse(code = 400, message = "Bad Request", response = Error.class), @ApiResponse(code = 422, message = "Invalid data", response = Error.class), @ApiResponse(code = 500, message = "Internal Server Error", response = Error.class) })
public Response getEmployee()  {
        EmployeeService employeeService = new EmployeeService();
        Employee empDetails = employeeService.getEmployee();
        Response response;
        LOGGER.debug("Fetching employee");
        GenericEntity<Employee> entity = new GenericEntity<Employee>(empDetails){}; 
        response = Response.status(200).entity(entity).build();
        return response;
    }
}

स्वैगर के घटक जिनका हम यहां उपयोग करते हैं वे हैं:

1. @Api(tags = {"Employee"}) - यह एनोटेशन स्वैगर को बताएगा कि वेब सेवा का शीर्षक क्या होना चाहिए। इस मामले में शीर्षक " Employee " है। कृपया ध्यान दें कि स्वैगर डॉक्यूमेंटेशन लिखते समय REST WS लिखते समय कुछ मानक भी लागू होते हैं जैसे शीर्षक " GetEmployee " या " DeleteEmployee " आदि नहीं होना चाहिए।
2. @ApiOperation(produces="application/json", value = "Fetch employee details", httpMethod="GET", notes = "<br>This service fetches Employee details", response = Employee.class) - यह एनोटेशन संक्षिप्त विचार प्रदान करता है अपने वेब सेवा के बारे में।
   • प्रतिक्रिया के प्रारूप produces वर्णन produces ,
   • value webservice के बारे में संक्षिप्त विचार का वर्णन करता है
   • notes किसी भी मामले में इस वेब सेवा के बारे में विस्तृत जानकारी का वर्णन करता है।
3. @ApiResponses(value = { @ApiResponse(code = 200,response = Employee.class, message = "Successful operation"),@ApiResponse(code = 400, message = "Bad Request", response = Error.class), @ApiResponse(code = 422, message = "Invalid data", response = Error.class), @ApiResponse(code = 500, message = "Internal Server Error", response = Error.class) }) - यह एनोटेशन हमें एक रास्ता प्रदान करता है HTTP स्टेटस कोड्स के विभिन्न प्रकारों को संभालें जो इस वेब्स सर्विस का उपभोग करते हुए प्रतिक्रिया के रूप में प्राप्त किया जा सकता है। यह हमें त्रुटि कोड, इसके खिलाफ कस्टम संदेश सेट करने की अनुमति देता है और यहां तक कि आवश्यकता होने पर हमें अलग त्रुटि वर्ग में उस त्रुटि को पकड़ने की अनुमति देता है।

अंत में, हमें वास्तविक सेवा वर्ग तैयार करना होगा, जिसमें ग्राहक द्वारा वेबबेस सेवा का उपभोग करने पर कर्मचारियों के विवरण प्राप्त होंगे। आप इसे आवश्यकतानुसार लागू कर सकते हैं। निम्नलिखित डेमो उद्देश्य के लिए नमूना सेवा है:

public class EmployeeService {

public Employee getEmployee() {
    Employee employee = new Employee();
    employee.setId("1");
    employee.setName("Test");
    employee.setDept("IT");
    return employee;
    }
}

अब आप स्वैगर UI पर अपने दस्तावेज़ देखने के लिए तैयार हैं। अपने स्वैगर प्रोजेक्ट को तैनात करें और सर्वर शुरू करें। अब ब्राउजर में जाएं और अपने प्रोजेक्ट के URL को हिट करें। इस मामले में इसके

http: // localhost: 8080 / अकड़-ui /

यदि स्वैगर ठीक से कॉन्फ़िगर किया गया है, तो आपको निम्न स्क्रीन देखने में सक्षम होना चाहिए:

अब, अपने webservice प्रलेखन को देखने के लिए अपने प्रोजेक्ट का "base_url / rest / swagger.json" टेक्स्टबॉक्स ( http://exampl.com/api) में दें, जिसे आप ऊपर की छवि में देख सकते हैं। उस URL को टेक्स्टबॉक्स में प्रदान करने के बाद, आप अपने REST वेबसर्विस के दस्तावेज़ीकरण प्रदान करते हुए निम्नलिखित स्क्रीन देख सकते हैं:

पाठ बॉक्स जहां " api key " को ऊपर की छवि में लिखा गया है, आप विशिष्ट हेडर या मुख्य मूल्य प्रदान कर सकते हैं यदि आपकी परियोजना उपयोगकर्ता आईडी, आदि के आधार पर प्रमाणीकरण की तरह मांग करती है। उसके लिए आपको <input placeholder="api_key" ...... शुरू होने वाले टैग के तहत index.html में बदलाव करने होंगे।

स्वैगर-यूआई का एक और अतिरिक्त लाभ है, यह एक बटन प्रदान करता है " Try it out! "। यह बटन आपको यह देखने के लिए सक्षम करता है कि इस वेब सेवा की प्रतिक्रिया क्या हो सकती है। इस स्थिति के लिए, यदि हम उस बटन पर क्लिक करते हैं, तो यह स्क्रीन पर निम्नलिखित प्रतिक्रिया देगा:

तो यह Swagger UI के लिए नमूना डेमो है। ऐसे कई विकल्प हैं जो आप अभी भी REST कंट्रोलर लिखते समय खोज सकते हैं जो आपको अधिक एनोटेशन और उनकी विशेषताओं का उपयोग करके प्रलेखन स्तर पर मदद करेगा।