创建swagger的springboot-stater

创建swagger的springboot-stater

创建sawgger-springboot-starter项目

POM配置
pom引入swagger依赖
        <!-- swagger 依赖 -->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.9.2</version>
        </dependency>
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>2.9.2</version>
        </dependency>

pom引入springboot starter相关依赖

        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-configuration-processor</artifactId>
            <optional>true</optional>
        </dependency>
        <dependency>
            <groupId>org.projectlombok</groupId>
            <artifactId>lombok</artifactId>
            <optional>true</optional>
        </dependency>

swagger配置

相关的配置属性,将会在yml文件中进行配置

package com.swagger.config;


import lombok.Data;
import org.springframework.boot.context.properties.ConfigurationProperties;

@Data
@ConfigurationProperties(prefix = "swagger")
public class SwaggerProperties {

    //需要扫描的包路径
    private String basePackage = "com";
    //显示的标题
    private String title = "swagger";
    //联系人
    private  String contactName;
    //联系地址
    private  String contactUrl;
    //联系邮件地址
    private  String contactEmail;
    //文档版本号
    private String version;
    //描述
    private  String description;
    //
    private  String termsOfServiceUrl;
    
    private  String license;
    private  String licenseUrl;

}

配置类

package com.swagger.config;


import lombok.extern.slf4j.Slf4j;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.context.properties.EnableConfigurationProperties;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger.web.UiConfiguration;

/**
 *功能描述 
 * @author lgj
 * @Description swagger 配置类
 * @date 6/5/19
*/
@Slf4j
@Configuration
@EnableConfigurationProperties(SwaggerProperties.class)
public class SwaggerConfig {

    @Autowired
    private SwaggerProperties swaggerProperties;


    @Bean
    public Docket docket() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                //为当前包路径
                .apis(RequestHandlerSelectors.basePackage(swaggerProperties.getBasePackage()))
                .paths(PathSelectors.any())
                .build();
    }
    //构建 api文档的详细信息函数,注意这里的注解引用的是哪个
    private ApiInfo apiInfo() {

        log.info("swaggerProperties = " + swaggerProperties);
        return new ApiInfoBuilder()
                //页面标题
                .title(swaggerProperties.getTitle())
                //创建人
                .contact(new Contact(swaggerProperties.getContactName(), swaggerProperties.getContactUrl(), swaggerProperties.getContactEmail()))
                //版本号
                .version(swaggerProperties.getVersion())
                //描述
                .description(swaggerProperties.getDescription())
                .license(swaggerProperties.getLicense())
                .licenseUrl(swaggerProperties.getLicenseUrl())
                .termsOfServiceUrl(swaggerProperties.getTermsOfServiceUrl())
                .build()
                ;
    }


    @Bean
    UiConfiguration uiConfig() {
        return new UiConfiguration(null, "list", "alpha", "schema",
                UiConfiguration.Constants.DEFAULT_SUBMIT_METHODS, false, true, 60000L);
    }


}

既然作为starter,还需要指定项目启动时的配置类,因为其他项目引用时没有指定扫描该类,那么就不会创建相关的bean。
因此需要在starter中指定。
在resource中创建文件 META-INF/spring.factories

spring.factories文件内容,通过EnableAutoConfiguration指定。

org.springframework.boot.autoconfigure.EnableAutoConfiguration=com.swagger.config.SwaggerConfig

swagger-springboot-starter创建完成 /

 

 

创建一个WEB应用进行测试

引入上面starter的依赖

     <dependency>
            <groupId>com.swagger</groupId>
            <artifactId>swagger-springboot-starter</artifactId>
            <version>1.0.0</version>
        </dependency>
server:
  port: 8900


swagger:
  basePackage: com
  title: "demo ui doc"
  contactName: "libai"
  contactUrl: contactUrl-demo
  contactEmail: contactEmail-demo
  version: v1.0.0
  description: description-demo
  termsOfServiceUrl: termsOfServiceUrl-demo
  license: license-demo
  licenseUrl: licenseUrl-demo

创建一个controller

package com.demo.demo;


import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import io.swagger.annotations.ApiParam;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

import java.util.Date;

@Api(value = "/demo",description = "demo controller")
@RestController
@RequestMapping("/demo")
public class WebController {


    @ApiOperation(value = "/demo/1",notes="这是demo1",tags="{tag1,tag2}",response=String.class,httpMethod= "GET")
    @ApiParam(name = "name",value = "libai")
    @GetMapping("/1")
    public String demo1(String name){

        return   name + ":" + new Date().toString();
    }

    @ApiOperation(value = "/demo/2",notes="这是demo2",tags="{tag3,tag4}",response=String.class,httpMethod= "POST")
    @PostMapping("/2")
    public String demo2(String name){

        return   name + ":" + new Date().toString();
    }
}

注意这里使用@Api和@ApiOperation,@ApiParam等实现接口说明。
要说明相关的类和方法。以便swagger-ui查看到。
更多使用方法参考本博文

在启动类上添加注解@EnableSwagger2

@EnableSwagger2
@SpringBootApplication
public class DemoApplication {

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

}

测试

启动DemoApplication应用,访问swagger-ui界面,地址http://localhost:80800/swagger-ui.html

可以看到之前代码中的相关配置。