Swagger+SpringCloud

Swagger是一种自动生成整合API文档的组件，将开发整理文档的工作与代码相结合，节省开发时间，增加工作效率。

Jhipster代码生成器锁生成的工程，已经整合了Swagger后端部分。

 <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>${springfox.version}</version>
            <exclusions>
                <exclusion>
                    <groupId>org.mapstruct</groupId>
                    <artifactId>mapstruct</artifactId>
                </exclusion>
            </exclusions>
        </dependency>

 

Swagger所需的依赖：

<dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>${springfox-version}</version>
        </dependency>
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>${springfox-version}</version>
        </dependency>

所以我们只需要引入ui的依赖，那么UI与后端部分实际上就已经可以了 。

下面看看Swagger的配置

/*
 * Copyright 2016-2017 the original author or authors from the JHipster project.
 *
 * This file is part of the JHipster project, see https://jhipster.github.io/
 * for more information.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

package io.github.jhipster.config.apidoc;

import static springfox.documentation.builders.PathSelectors.regex;

import java.util.ArrayList;

import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.beans.factory.annotation.Value;
import org.springframework.boot.autoconfigure.condition.ConditionalOnClass;
import org.springframework.context.annotation.*;
import org.springframework.http.ResponseEntity;
import org.springframework.util.StopWatch;

import com.fasterxml.classmate.TypeResolver;

import io.github.jhipster.config.JHipsterConstants;
import io.github.jhipster.config.JHipsterProperties;
import springfox.bean.validators.configuration.BeanValidatorPluginsConfiguration;
import springfox.documentation.schema.TypeNameExtractor;
import springfox.documentation.service.*;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

/**
 * Springfox Swagger configuration.
 *
 * Warning! When having a lot of REST endpoints, Springfox can become a performance issue. In that case, you can use a
 * specific Spring profile for this class, so that only front-end developers have access to the Swagger view.
 */
@Configuration
@ConditionalOnClass({ ApiInfo.class, BeanValidatorPluginsConfiguration.class })
@EnableSwagger2
@Import(BeanValidatorPluginsConfiguration.class)
@Profile(JHipsterConstants.SPRING_PROFILE_SWAGGER)
public class SwaggerConfiguration {

    private final Logger log = LoggerFactory.getLogger(SwaggerConfiguration.class);
    private final JHipsterProperties jHipsterProperties;

    public SwaggerConfiguration(JHipsterProperties jHipsterProperties) {
        this.jHipsterProperties = jHipsterProperties;
    }

    /**
     * Springfox configuration for the API Swagger docs.
     *
     * @return the Swagger Springfox configuration
     */
    @Bean
    public Docket swaggerSpringfoxApiDocket() {
        log.debug("Starting Swagger");
        StopWatch watch = new StopWatch();
        watch.start();
        Contact contact = new Contact(
            jHipsterProperties.getSwagger().getContactName(),
            jHipsterProperties.getSwagger().getContactUrl(),
            jHipsterProperties.getSwagger().getContactEmail());

        ApiInfo apiInfo = new ApiInfo(
            jHipsterProperties.getSwagger().getTitle(),
            jHipsterProperties.getSwagger().getDescription(),
            jHipsterProperties.getSwagger().getVersion(),
            jHipsterProperties.getSwagger().getTermsOfServiceUrl(),
            contact,
            jHipsterProperties.getSwagger().getLicense(),
            jHipsterProperties.getSwagger().getLicenseUrl(),
            new ArrayList<>());

        Docket docket = new Docket(DocumentationType.SWAGGER_2)
            .apiInfo(apiInfo)
            .forCodeGeneration(true)
            .directModelSubstitute(java.nio.ByteBuffer.class, String.class)
            .genericModelSubstitutes(ResponseEntity.class)
            .select()
            .paths(regex(jHipsterProperties.getSwagger().getDefaultIncludePattern()))
            .build();
        watch.stop();
        log.debug("Started Swagger in {} ms", watch.getTotalTimeMillis());
        return docket;
    }

    /**
     * Springfox configuration for the management endpoints (actuator) Swagger docs.
     *
     * @param appName               the application name
     * @param managementContextPath the path to access management endpoints
     * @param appVersion            the application version
     * @return the Swagger Springfox configuration
     */
    @Bean
    public Docket swaggerSpringfoxManagementDocket(@Value("${spring.application.name}") String appName,
        @Value("${management.context-path}") String managementContextPath,
        @Value("${info.project.version}") String appVersion) {
        return new Docket(DocumentationType.SWAGGER_2)
            .apiInfo(new ApiInfo(appName + " management API", "Management endpoints documentation",
                appVersion, "", ApiInfo.DEFAULT_CONTACT, "", "", new ArrayList<VendorExtension>()))
            .groupName("management")
            .forCodeGeneration(true)
            .directModelSubstitute(java.nio.ByteBuffer.class, String.class)
            .genericModelSubstitutes(ResponseEntity.class)
            .select()
            .paths(regex(managementContextPath + ".*"))
            .build();
    }

    @Bean
    PageableParameterBuilderPlugin pageableParameterBuilderPlugin(TypeNameExtractor nameExtractor,
        TypeResolver resolver) {

        return new PageableParameterBuilderPlugin(nameExtractor, resolver);
    }
}

主要看返回Docket的两个方法，这个Docket和ApiInfo对象，后面解释，只需要知道这两个方法定义的就是你对后面要展示的页面的分组情况，其中groupName就是两个组名，默认已经占用了default（对应羡慕生成后创建的所有restful接口）和management（基本对应端点监控部分）两个。

实际上这个时候我们就已经完成了Swagger配置的工作，可以看下效果了。

我们想添加一个自己的API组

@Configuration
@EnableSwagger2
public class SwaggerConfiguration2 {
    public SwaggerConfiguration2(JHipsterProperties jHipsterProperties) {
        super(jHipsterProperties);
    }

    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
            .apiInfo(apiInfo())
            .groupName("api")
            .select()
            .apis(RequestHandlerSelectors.basePackage("com.ccidit.wsgen.web.rest"))
            .paths(PathSelectors.any())
            .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
            .title("文书部分构建的RESTful接口API")
            .description("只包含业务相关接口")
            .contact("***")
            .version("1.0")
            .build();
    }
}

这样我们就能添加一个自己的API组：

 

还记得之前的Docket对象吗？

现在差不多就能明白了吧。Docket对象实际上就是你多Swagger的扫描路径，描述等一系列配置。Apiinfo实际上就是页面上一些摘要信息的配置。

这里还有一个坑，当你点击测试按钮时

它的测试地址是：http://服务名/api地址 的形式，所以这里我们还需要通过host方法修改它的访问地址。

@Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2).host("127.0.0.1:8084")
            .apiInfo(apiInfo())
            .groupName("api")
            .select()
            .apis(RequestHandlerSelectors.basePackage("com.ccidit.wsgen.web.rest"))
            .paths(PathSelectors.any())
            .build();
    }

上面说的默认的两个想修改只能从上下文取然后改了，比较麻烦。

问题：这里最后实际上还有一个报错，页面上的error

说是一个接口访问不了，暂时还未解决。

补充：前端页面校验的问题，放弃了，查阅的资料说需要解包，修改前端的代码，太麻烦了。

 

参考：http://blog.didispace.com/springbootswagger2/

转载于:https://my.oschina.net/zyldsy/blog/1631718