本篇文档的基础是《sb-helloworld笔记》。在基础上整合swagger。
现在的技术趋势是前后端分离,前端展示,后端业务处理。前端和后端的唯一联系,变成了API接口;API文档变成了前后端开发人员联系的纽带,变得越来越重要,swagger就是一款让你更好的书写API文档的框架。
1、引入依赖
<properties>
<!-- swagger2若使用2.6.0版本,会出现Eureka服务注册到服务中心,服务名为UNKNOWN的情况 -->
<swagger2.version>2.7.0</swagger2.version>
</properties>
---------------------------------------------------------------
<!-- swagger2 -->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>${swagger2.version}</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>${swagger2.version}</version>
</dependency>
<dependency>
<groupId>io.swagger</groupId>
<artifactId>swagger-core</artifactId>
<version>2.0.0-rc2</version>
</dependency>
2、swagger配置类
- @Configuration:配置注解
- @Bean:是一个方法级别上的注解,主要用在@Configuration注解的类里,也可以用在@Component注解的类里。添加的bean的id为方法名。必看:https://www.cnblogs.com/feiyu127/p/7700090.html
- @EnableSwagger2:启用Swagger2
- @ConditionalOnExpression:springboot中@ConditionalOnExpression注解,在特定情况下使用相关配置或者实例化bean。通过在配置文件中增加application.profile项,确定是线下环境还是线上环境。如果是线上环境,则自动关闭swagger,避免了线上暴露接口。必看:https://blog.csdn.net/Winter_chen001/article/details/80391413
import org.springframework.boot.autoconfigure.condition.ConditionalOnExpression;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.context.request.async.DeferredResult;
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.swagger2.annotations.EnableSwagger2;
@Configuration
@EnableSwagger2
@ConditionalOnExpression("'${application.profile}'!='online'")
public class SwaggerConfiguration {
@Bean
public Docket createRestApi() {
return new Docket(DocumentationType.SWAGGER_2).groupName("hcm portal")
.genericModelSubstitutes(DeferredResult.class)
.useDefaultResponseMessages(false).forCodeGeneration(false)
.apiInfo(apiInfo())
.select()
.apis(RequestHandlerSelectors.basePackage("com.everyday.helloworld"))
.paths(PathSelectors.regex("/.*"))
.build();
}
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("快乐每一天")
.description("生活还是要快乐的")
.version("1.0")
.contact(new Contact("大金刚", "", "[email protected]"))
.termsOfServiceUrl("www.baidu.com")
.build();
}
}
3、swagger注解
swagger的注解在controller层和model类上。
controller层注解:
@Api(description = "controller层")
public class HelloController {}
@ApiOperation(value = "测试方法上的swagger注解", notes = "tyl")
public User swagger() {}
model类上的注解:
@Setter
@Getter
@ToString
@ApiModel(value = "User类")
public class User {
@ApiModelProperty(value = "名称", example = "jack")
private String name;
}
启动项目,访问:http://localhost:8081/swagger-ui.html
代码:整合入sb-helloworld项目