स्प्रिंग एमवीसी एप्लिकेशन में स्वैगर को लागू करने का एक 'सरल' तरीका

Question 1

मेरे पास सरल स्प्रिंग (कोई स्प्रिंग बूट, कोई फैंसी सामान नहीं!) में लिखा गया एक रेस्टफुल एपीआई है। मुझे इसमें स्वैगर को लागू करने की आवश्यकता है। अब तक, इंटरनेट पर हर पेज ने मुझे केवल भ्रमित कॉन्फ़िगरेशन और फूला हुआ कोड के साथ पागल कर दिया है जो मुझे बिल्कुल भी पोर्टेबल नहीं मिला।

क्या किसी के पास एक नमूना परियोजना (या विस्तृत चरणों का एक सेट) है जो मुझे इसे पूरा करने में मदद कर सकती है? विशेष रूप से, मैं एक अच्छे नमूने की तलाश में हूं जो स्वैगर-स्प्रिंगमिक्स का उपयोग करता है। मुझे पता है कि इसमें 'नमूने' हैं, लेकिन सबसे अच्छा है, गूढ़ कोड हतोत्साहित कर रहा है।

मुझे स्पष्ट करना चाहिए कि मैं "क्यों स्वैगर बस सबसे अच्छा है" की तलाश में नहीं हूं। मैं उपयोग नहीं कर रहा हूं (और मेरे वर्तमान कार्य के लिए उपयोग नहीं होगा) स्प्रिंग बूट या ऐसा।

Question 2

स्प्रिंगफ़ॉक्स (स्वैगर स्पेस 2.0, करंट)

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

मावेन निर्भरता

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.5.0</version>
</dependency>

नंगे-न्यूनतम क्रियान्वयन कम-से-कम एक जैसा दिखता है, लेकिन अब Docketकक्षा के बजाय कक्षा का उपयोग करता है SwaggerSpringMvcPlugin:

@Configuration
@EnableSwagger2
public class SwaggerConfig {

    @Bean
    public Docket api(){
        return new Docket(DocumentationType.SWAGGER_2)
            .select()
            .apis(RequestHandlerSelectors.any())
            .paths(PathSelectors.regex("/api/.*"))
            .build()
            .apiInfo(apiInfo());
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
            .title("TITLE")
            .description("DESCRIPTION")
            .version("VERSION")
            .termsOfServiceUrl("http://terms-of-services.url")
            .license("LICENSE")
            .licenseUrl("http://url-to-license.com")
            .build();
    }

}

अब आपका स्वैगर 2.0 एपीआई प्रलेखन उपलब्ध होगा http://myapp/v2/api-docs।

नोट: यदि आप स्प्रिंग बूट का उपयोग नहीं कर रहे हैं, तो आपको जैकसन-डेटाबाइंड निर्भरता को जोड़ना चाहिए। चूंकि स्प्रिंगबॉट डेटाबाइंडिंग के लिए जैकसन का उपयोग करता है।

स्वैगर UI समर्थन जोड़ना अब और भी आसान है। यदि आप मावेन का उपयोग कर रहे हैं, तो स्वैगर यूआई वेबर के लिए निम्न निर्भरता जोड़ें:

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.5.0</version>
</dependency>

यदि आप स्प्रिंग बूट का उपयोग कर रहे हैं, तो आपके वेब ऐप को स्वचालित रूप से आवश्यक फ़ाइलों को चुनना चाहिए और यूआई को http://myapp/swagger-ui.html(पूर्व में:) दिखाना चाहिए http://myapp/springfox। यदि आप स्प्रिंग बूट का उपयोग नहीं कर रहे हैं, तो नीचे दिए गए उत्तर में yuriy-tumakha का उल्लेख है, तो आपको फ़ाइलों के लिए संसाधन हैंडलर को पंजीकृत करना होगा। जावा कॉन्फ़िगरेशन इस तरह दिखता है:

@Configuration
@EnableWebMvc
public class WebAppConfig extends WebMvcConfigurerAdapter {

    @Override 
    public void addResourceHandlers(ResourceHandlerRegistry registry) {
        registry.addResourceHandler("swagger-ui.html").addResourceLocations("classpath:/META-INF/resources/");
        registry.addResourceHandler("/webjars/**").addResourceLocations("classpath:/META-INF/resources/webjars/");
    }

}

नया स्टैटिक डॉक्यूमेंटेशन जनरेशन फीचर भी काफी अच्छा लगता है, हालाँकि मैंने इसे खुद नहीं आजमाया है।

स्वैगर-स्प्रिंगएमवीसी (स्वैगर कल्पना 1.2, पुराना)

स्वैगर-स्प्रिंगएमवीसी के लिए प्रलेखन थोड़ा भ्रमित हो सकता है, लेकिन इसे स्थापित करना वास्तव में अविश्वसनीय रूप से आसान है। सबसे सरल कॉन्फ़िगरेशन के लिए SpringSwaggerConfigबीन बनाने और एनोटेशन-आधारित कॉन्फ़िगरेशन को सक्षम करने की आवश्यकता होती है (जो आप संभवतः अपने स्प्रिंग एमवीसी प्रोजेक्ट में पहले से करते हैं):

<mvc:annotation-driven/>
<bean class="com.mangofactory.swagger.configuration.SpringSwaggerConfig" />

हालाँकि, मुझे लगता है SwaggerSpringMvcPluginकि पिछले एक्सएमएल-परिभाषित बीन के बजाय, कस्टम स्वैगर कॉन्फ़िगरेशन का उपयोग करके इसे परिभाषित करने के अतिरिक्त कदम उठाने के लिए यह अच्छी तरह से लायक है :

@Configuration
@EnableSwagger
@EnableWebMvc
public class SwaggerConfig {

    private SpringSwaggerConfig springSwaggerConfig;

    @SuppressWarnings("SpringJavaAutowiringInspection")
    @Autowired
    public void setSpringSwaggerConfig(SpringSwaggerConfig springSwaggerConfig) {
        this.springSwaggerConfig = springSwaggerConfig;
    }

    @Bean
    public SwaggerSpringMvcPlugin customImplementation(){

        return new SwaggerSpringMvcPlugin(this.springSwaggerConfig)
                .apiInfo(apiInfo())
                .includePatterns(".*api.*"); // assuming the API lives at something like http://myapp/api
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
            .title("TITLE")
            .description("DESCRIPTION")
            .version("VERSION")
            .termsOfServiceUrl("http://terms-of-services.url")
            .license("LICENSE")
            .licenseUrl("http://url-to-license.com")
            .build();
    }

}

जब आप अपना एप्लिकेशन चलाते हैं, तो आपको अब अपना API युक्ति बनाना चाहिए http://myapp/api-docs। फैंसी स्वैगर UI सेट अप करने के लिए, आपको GitHub प्रोजेक्ट से स्थिर फ़ाइलों को क्लोन करना होगा और उन्हें अपने प्रोजेक्ट में डालना होगा। सुनिश्चित करें कि आपकी परियोजना स्थिर HTML फ़ाइलों की सेवा के लिए कॉन्फ़िगर की गई है:

<mvc:resources mapping="*.html" location="/" />

फिर index.htmlSwagger UI distनिर्देशिका के शीर्ष स्तर पर फ़ाइल को संपादित करें । फ़ाइल के शीर्ष पर, आपको कुछ जावास्क्रिप्ट दिखाई देगी api-docsजो किसी अन्य परियोजना के URL को संदर्भित करती है । अपनी परियोजना के स्वैगर दस्तावेज़ को इंगित करने के लिए इसे संपादित करें:

  if (url && url.length > 1) {
    url = url[1];
  } else {
    url = "http://myapp/api-docs";
  }

अब जब आप नेविगेट करते हैं http://myapp/path/to/swagger/index.html, तो आपको अपनी परियोजना के लिए स्वैगर UI उदाहरण देखना चाहिए।

Question 3

WebJar निर्भरता और संसाधन मैपिंग को जोड़ने के बाद स्प्रिंगफॉक्स स्वैगर यूआई मेरे लिए काम करता है। http://www.webjars.org/documentation#springmvc

    <dependency>
        <groupId>io.springfox</groupId>
        <artifactId>springfox-swagger2</artifactId>
        <version>2.2.2</version>
    </dependency>
    <dependency>
        <groupId>io.springfox</groupId>
        <artifactId>springfox-swagger-ui</artifactId>
        <version>2.2.2</version>
    </dependency>
    <dependency>
        <groupId>org.webjars</groupId>
        <artifactId>bootstrap</artifactId>
        <version>3.3.5</version>
    </dependency>

वसंत-servlet.xml:

<mvc:resources mapping="swagger-ui.html" location="classpath:/META-INF/resources/"/>
<mvc:resources mapping="/webjars/**" location="classpath:/META-INF/resources/webjars/"/>

या वसंत एनोटेशन https://github.com/springfox/springfox-demos/blob/master/spring-java-swagger/src/main/java/springfoxdemo/java/swagger/SpringConfig.java

Swagger2 सक्षम होना चाहिए

 @EnableSwagger2
 public class SwaggerConfiguration {
 }

Question 4

आप swagger.json को उत्पन्न करने के लिए स्वैगर-मावेन-प्लगइन का उपयोग करने पर भी विचार कर सकते हैं और इसे अपने स्टेटिक स्वैगर-उई में कॉपी कर सकते हैं।

कृपया इस रेपो पर स्प्रिंग एमवीसी एनोटेशन के साथ काम करने वाले प्लगइन के सरल नमूने की जाँच करें:

https://github.com/khipis/swagger-maven-example

या JAX-RS के लिए

https://github.com/kongchen/swagger-maven-example