Categories
Uncategorized

springboot of swagger Quick Start

springboot of swagger Quick Start

Brief introduction

Introduction

We may have used the swagger, the interface can display information quickly by the FBI and the front ui page.

No contact with small partners can refer to the official website of the article to find out about the next demo page.

Multi-application

Of course, you can configure a single application class loader SwaggerConfig under buildDocket, you can quickly build a good swagger.

Code is as follows:

/**
 * Swagger2配置类
 * 在与spring boot集成时,放在与Application.java同级的目录下。
 * 通过@Configuration注解,让Spring来加载该类配置。
 * 再通过@EnableSwagger2注解来启用Swagger2。
 */
@Configuration
@EnableSwagger2
public class SwaggerConfig {
    
    /**
     * 创建API应用
     * apiInfo() 增加API相关信息
     * 通过select()函数返回一个ApiSelectorBuilder实例,用来控制哪些接口暴露给Swagger来展现,
     * 本例采用指定扫描的包路径来定义指定要建立API的目录。
     * 
     * @return
     */
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.swaggerTest.controller"))
                .paths(PathSelectors.any())
                .build();
    }
    
    /**
     * 创建该API的基本信息(这些基本信息会展现在文档页面中)
     * 访问地址:http://项目实际地址/swagger-ui.html
     * @return
     */
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("Spring Boot中使用Swagger2构建RESTful APIs")
                .description("更多请关注http://www.baidu.com")
                .termsOfServiceUrl("http://www.baidu.com")
                .contact("sunf")
                .version("1.0")
                .build();
    }
}

Modular -Starter

reason

Have worked on micro-service small partners should experience before. In the case where many micro service module, each module must be configured to load a class such swagger. Each module caused the presence of roughly the same SwaggerConfig, in extreme cases, some friends after copying other modules SwaggerConfig transform, load still found no cases swagger, resulting in obviously copied, so why not load, this investigation bug and time-consuming.

On top of this, it is possible to construct a swagger-starter module, only need to reference a JAR, load some special configuration, can quickly use of a partial function swagger.

design

Create a module swagger-spring-boot-starter.
    Function is as follows:

    Load the SwaggerConfig.

    Configure swagger by configuration.

    Enable load notes.

1. Create SwaggerConfig

SwaggerConfig previous agreement and, just inside the configuration needs to externalize.

@Configuration
@PropertySource(value = "classpath:swagger.properties", ignoreResourceNotFound = true, encoding = "UTF-8")
@EnableConfigurationProperties(SwaggerProperties.class)
public class SwaggerConfig {

  @Resource
  private SwaggerProperties swaggerProperties;

  @Bean
  public Docket buildDocket() {
    return new Docket(DocumentationType.SWAGGER_2)
        .apiInfo(buildApiInf())
        .select()
        .apis(RequestHandlerSelectors.basePackage(""))
        .paths(PathSelectors.any())
        .build();
  }

  private ApiInfo buildApiInf() {
    return new ApiInfoBuilder()
        .title(swaggerProperties.getTitle())
        .description(swaggerProperties.getDescription())
        .termsOfServiceUrl(swaggerProperties.getTermsOfServiceUrl())
        .contact(new Contact("skyworth", swaggerProperties.getTermsOfServiceUrl(), ""))
        .version(swaggerProperties.getVersion())
        .build();
  }
}

2. Create a configuration-related SwaggerProperties

Configuration loaded swagger.properties under the resources directory by @PropertySource comment.

Create SwaggerProperties configuration class which contains a number of common attributes to be used is generally swagger initialization, such as scanning package path, title and the like.

@Data
@ToString
@ConfigurationProperties(SwaggerProperties.PREFIX)
public class SwaggerProperties {

  public static final String PREFIX = "swagger";

  /**
   * 文档扫描包路径
   */
  private String basePackage = "";

  /**
   * title 如: 用户模块系统接口详情
   */
  private String title = "深兰云平台系统接口详情";

  /**
   * 服务文件介绍
   */
  private String description = "在线文档";

  /**
   * 服务条款网址
   */
  private String termsOfServiceUrl = "https://www.deepblueai.com/";

  /**
   * 版本
   */
  private String version = "V1.0";


}

做好这两件事情基本大工搞成了,为了更好的使用配置,在idea里和官方starter包一样,我们还需要配置一个additional-spring-configuration-metadata.json,让我们自己的配置也具有提示的功能,具体介绍请产考:配置提示 配置提示 配置提示 配置提示 配置提示 …

3. Load SwaggerConfig other characteristics

Because it is a starter module, others might directory project directory and starter module is inconsistent, resulting in less than SwaggerConfig class is loaded, we need to use spring.factories to SwaggerConfig class to spring loaded container.

resources/META-INF

org.springframework.boot.autoconfigure.EnableAutoConfiguration=\
  io.purge.swagger.SwaggerConfig

Of course, this time based on Enable way to load SwaggerConfig.

Creating @EnableSwaggerPlugins annotation classes, use @Import (SwaggerConfig.class) will SwaggerConfig import large work anyhow.

@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.TYPE)
@Import(SwaggerConfig.class)
@EnableSwagger2
public @interface EnableSwaggerPlugins {

}

use

Add dependent

I have written a good swagger through the maven package, own project references.


  com.purgeteam
  swagger-spring-boot-starter
  0.1.0.RELEASE

Swagger.properties configuration file

  • Swagger.properties configuration in resources to create their own project directory module

  • swagger.properties generally configured as follows

swagger.basePackage="swagger扫描项目包路径"
swagger.title="swagger网页显示标题"
swagger.description="swagger网页显示介绍"

Add @EnableSwaggerPlugins startup class notes.

@EnableSwaggerPlugins
@SpringBootApplication
public class FrontDemoApplication {

  public static void main(String[] args) {
    SpringApplication.run(FrontDemoApplication.class, args);
  }

}

Visit http: // ip: port /swagger-ui.html check swagger-ui is normal.

to sum up

Simple starter code writing can reduce the complexity of new modules, with simple configuration you can use the corresponding features, reducing unnecessary errors in copying code.

Sample Code Address: swagger-spring-boot

Leave a Reply