如何使用swaggerui:
1. 创建maven项目:
2. 引入springMVC
修改web.xml
<?xml version="1.0" encoding="UTF-8"?>
<web-app xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns="http://xmlns.jcp.org/xml/ns/javaee"
xsi:schemaLocation="http://xmlns.jcp.org/xml/ns/javaee http://xmlns.jcp.org/xml/ns/javaee/web-app_3_1.xsd"
id="WebApp_ID"
version="3.1">
<display-name>Archetype Created Web Application</display-name>
<servlet>
<servlet-name>MySpringMVCName</servlet-name>
<servlet-class>org.springframework.web.servlet.DispatcherServlet</servlet-class>
<init-param>
<param-name>contextConfigLocation</param-name>
<param-value>classpath:MySpringMVCName-servlet.xml</param-value>
</init-param>
<load-on-startup>1</load-on-startup>
</servlet>
<servlet-mapping>
<servlet-name>MySpringMVCName</servlet-name>
<url-pattern>/</url-pattern>
</servlet-mapping>
<listener>
<listener-class>org.springframework.web.context.ContextLoaderListener</listener-class>
</listener>
<context-param>
<param-name>contextConfigLocation</param-name>
<param-value>classpath:applicationContext.xml</param-value>
</context-param>
</web-app>
Pom.xml
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">
<modelVersion>4.0.0</modelVersion>
<groupId>com.harvetech</groupId>
<artifactId>maven-swagger-ui</artifactId>
<packaging>war</packaging>
<version>0.0.1-SNAPSHOT</version>
<name>maven-swagger-ui Maven Webapp</name>
<url>http://maven.apache.org</url>
<properties>
<springfox.version>2.7.0</springfox.version>
<spring.boot.version>1.5.6.RELEASE</spring.boot.version>
</properties>
<dependencies>
<dependency>
<groupId>junit</groupId>
<artifactId>junit</artifactId>
<version>3.8.1</version>
<scope>test</scope>
</dependency>
<!-- spring-web -->
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-web</artifactId>
<version>${spring.boot.version}</version>
</dependency>
</dependencies>
<build>
<finalName>maven-swagger-ui</finalName>
<plugins>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-compiler-plugin</artifactId>
<configuration>
<source>1.7</source>
<target>1.7</target>
</configuration>
</plugin>
</plugins>
</build>
</project>
3. 添加接口:
4. 测试接口:
5. 集成swagger
1) 引包
<properties>
<springfox.version>2.7.0</springfox.version>
</properties>
<!-- swagger2核心依赖 -->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>${springfox.version}</version>
</dependency>
<!-- swagger-ui为项目提供api展示及测试的界面 -->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>${springfox.version}</version>
</dependency>
引完包可以看到多了许多包,其中一个就是springfox-swagger-ui,其结构如下:
2) 添加SwaggerConfig
可以先加一个空内容的config类,只需要两个注解:
@Configuration
@EnableSwagger2
public class SwaggerConfig {
}
后面再来完善它。
3) 配置swagger-ui.html
我们希望通过访问
http://localhost:8080/maven-swagger-ui/swagger-ui.html
查看接口。
而此html是
springfox-swagger-ui-2.7.0.jar下的页面,因此需要配置。
有两种方式:
1.添加配置类:
package com.harvetech.utils;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.EnableWebMvc;
import org.springframework.web.servlet.config.annotation.ResourceHandlerRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurerAdapter;
@Configuration
@EnableWebMvc
public class WebAppConfig extends WebMvcConfigurerAdapter {
@Override
public void addResourceHandlers(ResourceHandlerRegistry registry) {
registry.addResourceHandler("swagger-ui.html").addResourceLocations("classpath:/META-INF/resources/");
registry.addResourceHandler("/webjars/**").addResourceLocations("classpath:/META-INF/resources/webjars/");
}
}
2.在springMVC配置文件中配置
<mvc:resources mapping="swagger-ui.html" location="classpath:/META-INF/resources/" />
<mvc:resources mapping="/webjars/**" location="classpath:/META-INF/resources/webjars/" />
两种方式效果一样。
4) 访问swagger-ui.html
可以看到,可以直接访问此页面了
5) Api注解
package com.harvetech.controller;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiImplicitParams;
import io.swagger.annotations.ApiOperation;
import org.springframework.http.MediaType;
import org.springframework.stereotype.Controller;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestMethod;
import org.springframework.web.bind.annotation.ResponseBody;
@Controller
@Api(description = "登录/注销接口",produces = MediaType.APPLICATION_JSON_UTF8_VALUE)
public class UserController {
@RequestMapping(value = "/users", method = RequestMethod.GET)
@ResponseBody
@ApiOperation(value = "获取用户接口")
//Valid values are {@code path}, {@code query}, {@code body}, {@code header} or {@code form}
@ApiImplicitParams({ @ApiImplicitParam(name = "id", value = "用户id",paramType = "query", required = true)})
public String getUser(String id){
String result = "name: " + "gary" + " id: " + id;
System.out.println(result);
return result;
}
@RequestMapping(value = "/login", method = RequestMethod.POST)
@ResponseBody
@ApiOperation(value = "登录接口")
@ApiImplicitParams({ @ApiImplicitParam(name = "name", value = "登录名",paramType = "query", required = true),
@ApiImplicitParam(name = "password", value = "登录密码",paramType = "query", required = true)})
public String login(String name, String password){
String result = "name: " + name + " password: " + password;
System.out.println(result);
return result;
}
}
可以看到输出结果:
· @Api:用在类上,说明该类的作用
· @ApiOperation:用在方法上,说明方法的作用
· @ApiImplicitParams:用在方法上包含一组参数说明
· @ApiImplicitParam:用在@ApiImplicitParams注解中,指定一个请求参数的各个方面
· paramType:参数放在哪个地方
· header-->请求参数的获取:@RequestHeader
· query-->请求参数的获取:@RequestParam
· path(用于restful接口)-->请求参数的获取:@PathVariable
· body(不常用)
· form(不常用)
· name:参数名
· dataType:参数类型
· required:参数是否必须传
· value:参数的意思
· defaultValue:参数的默认值
· @ApiResponses:用于表示一组响应
· @ApiResponse:用在@ApiResponses中,一般用于表达一个错误的响应信息
· code:数字,例如400
· message:信息,例如"请求参数没填好"
· response:抛出异常的类
· @ApiModel:描述一个Model的信息(这种一般用在post创建的时候,使用@RequestBody这样的场景,请求参数无法使用@ApiImplicitParam注解进行描述的时候)
· @ApiModelProperty:描述一个model的属性
6) 完善SwaggerConfig
package com.harvetech.utils;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.ParameterBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.schema.ModelRef;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.service.Parameter;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
import java.util.ArrayList;
import java.util.List;
@Configuration
@EnableSwagger2
public class SwaggerConfig {
@Bean
public Docket createRestApi() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.useDefaultResponseMessages(false)
.globalOperationParameters(globalOperationParameters())// 全局参数
.select()
.apis(RequestHandlerSelectors.any())
.paths(PathSelectors.regex("/.*"))// 监控所有路径
.build();
}
private List<Parameter> globalOperationParameters(){
ParameterBuilder builder = new ParameterBuilder();
Parameter parameter = builder.name("token").description("登录接口返回的token")
.modelRef(new ModelRef("string"))
.parameterType("header")
.required(false).build();
ArrayList<Parameter> parameters = new ArrayList<>();
parameters.add(parameter);
return parameters;
}
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("测试API文档")
.description("北京合源智慧科技发展有限公司 Copyright 2015-2023 (C) All Rights Reserved.")
.termsOfServiceUrl("http://www.harvetech.cn/")
.contact(new Contact("gary",null,"callmegary@163.com"))
.version("1.0")
.build();
}
}
其中apiInfo中配置一些页面展示信息,如文档名称、说明、联系人、邮箱、版本号等