原创

springboot集成swagger

Spring Boot 框架是目前非常流行的微服务框架,我们很多情况下使用它来提供 Rest API,而对于 Rest API 来说很重要的一部分内容就是文档,Swagger 为我们提供了一套通过代码和注解自动生成接口文档,这一点对于保证 API 文档的及时性将有很大的帮助,而且我们还可以通过Swagger调试接口,真的是相当方便。

1.配置

步骤1:pom.xml添加依赖

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

步骤2:配置Swagger

主要配置Swagger扫描的要生成接口文档的controller类包路径、配置api的标题、描述等信息,具体代码示例如下,@Configuration @EnableSwagger2 两个注解一定要加上

package net.javain.swagger.config;

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.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

@Configuration
@EnableSwagger2
public class SwaggerConfig {

@Bean
public Docket createRestApi() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
//要扫描的接口controller路径
.apis(RequestHandlerSelectors.basePackage("net.javain.swagger.controller"))
.paths(PathSelectors.any())
.build();
}

private ApiInfo apiInfo() {
return new ApiInfoBuilder()
//标题
.title("javain.net接口")
//描述
.description("")
.termsOfServiceUrl("")
//版本号
.version("1.0")
.build();
}
}

步骤三:配置Controller 和DTO

新建一个TestDTO作为数据传输对象,并用swagger的注解来标注字段的中文含义。

@ApiModelProperty 注解标识的属性,在生成api接口文档的时候,会显示出来 

package net.javain.swagger.dto;

import io.swagger.annotations.ApiModelProperty;

public class TestDTO {

@ApiModelProperty("姓名")
private String name;

@ApiModelProperty("年龄")
private int age;

@ApiModelProperty("性别,F:男,M:女")
private String sex;

public String getName() {
return name;
}

public void setName(String name) {
this.name = name;
}

public int getAge() {
return age;
}

public void setAge(int age) {
this.age = age;
}

public String getSex() {
return sex;
}

public void setSex(String sex) {
this.sex = sex;
}
}


新建一个HomeController,并用swagger注解来说明接口具体含义

@Api(value="",tags={"用户接口"}) ,该注解声明在controller类上

@ApiOperation(value="添加数据") ,该注解声明在方法上

package net.javain.swagger.controller;

import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import net.javain.swagger.dto.TestDTO;

@RestController
@RequestMapping("home")
@Api(value="",tags={"用户接口"})
public class HomeController {

@PostMapping("add")
@ApiOperation(value="添加数据")
public TestDTO addPerson(@RequestBody TestDTO testDTO){
return testDTO;
}
}

步骤四:运行项目

运行项目,在浏览器里访问 http://localhost:8080/swagger-ui.html 即可看到如下接口文档界面,如果访问404,则继续往下看

结合上面swagger的注解,可以看出每一个注解具体展示的位置在哪里。

如果访问地址,返回的是404,则只需添加如下配置代码即可,具体原因自行百度。

package net.javain.swagger.config;

import org.springframework.boot.autoconfigure.condition.ConditionalOnClass;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.CorsRegistry;
import org.springframework.web.servlet.config.annotation.ResourceHandlerRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;

import springfox.documentation.spring.web.SpringfoxWebMvcConfiguration;

@Configuration
@ConditionalOnClass(SpringfoxWebMvcConfiguration.class)
public class WebMvcConfig implements WebMvcConfigurer {

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

//registry.addResourceHandler("doc.html").addResourceLocations("classpath:/META-INF/resources/");

registry.addResourceHandler("/webjars/**")
.addResourceLocations("classpath:/META-INF/resources/webjars/");
}


}

步骤五:测试接口




正文到此结束
该篇文章的评论功能已被站长关闭