【原创】Sagger使用

Swagger使用

1. Spring MVC配置文件中的配置

 <mvc:annotation-driven/>

 <context:component-scan base-package="com.demo"/>

设置使用注解的类所在的jar包,只加载controller类

<mvc:default-servlet-handler />

使用 Swagger Restful API文档时，添加此注解

2. maven依赖

<properties>

           <spring.version>4.2.6.RELEASE</spring.version>

           <servlet.version>3.1.0</servlet.version>

           <swagger2.version>2.5.0</swagger2.version>

</properties>

<dependencies>

        <!-- swagger开始  -->

        <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.springfox</groupId>

            <artifactId>springfox-staticdocs</artifactId>

            <version>${swagger2.version}</version>

        </dependency>

        <!--  swagger结束  -->

        <!--spring-->

        <dependency>

            <groupId>org.springframework</groupId>

            <artifactId>spring-core</artifactId>

            <version>${spring.version}</version>

        </dependency>

        <dependency>

            <groupId>org.springframework</groupId>

            <artifactId>spring-web</artifactId>

            <version>${spring.version}</version>

        </dependency>

        <dependency>

            <groupId>org.springframework</groupId>

            <artifactId>spring-webmvc</artifactId>

            <version>${spring.version}</version>

        </dependency>

        <dependency>

            <groupId>org.springframework</groupId>

            <artifactId>spring-beans</artifactId>

            <version>${spring.version}</version>

        </dependency>

        <dependency>

            <groupId>org.springframework</groupId>

            <artifactId>spring-context</artifactId>

            <version>${spring.version}</version>

        </dependency>

        <dependency>

            <groupId>org.springframework</groupId>

            <artifactId>spring-context-support</artifactId>

            <version>${spring.version}</version>

        </dependency>

        <!--web-->

        <dependency>

            <groupId>javax.servlet</groupId>

            <artifactId>javax.servlet-api</artifactId>

            <version>${servlet.version}</version>

            <scope>provided</scope>

        </dependency>

</dependencies>

3. Swagger注解配置

@RequestMapping(value = "/add", method = RequestMethod.POST)

@ApiOperation(value = "添加用户", notes = "增加用户")

public Result<UserVo> add(@ApiParam(name = "userName",value = "用户昵称",required = true)@RequestParam(name = "userName",required = true)String userName,

 @ApiParam(name = "mobile",value = "手机",required = true)@RequestParam(name = "mobile",required = true)String mobile,

      @ApiParam(required = true, name = "email", value = "邮箱") @RequestParam(name = "email", required = true) String email ) {

     UserVo userVo=new UserVo();

     userVo.setUserId(System.currentTimeMillis());

     userVo.setUserName(userName);

        return new Result<UserVo>(Constants.SUCCESS,Constants.MSG_SUCCESS,userVo);

}

@ApiOperation(value = "创建用户", notes = "根据UserVo对象创建用户")  

@RequestMapping(value = "/create", method = RequestMethod.POST)  

public String postUser(@ApiParam(required = true, name = "userVo", value = "实体UserVo") @RequestBody UserVo userVo) {  

        return "success";

 } 

  

 @RequestMapping(value = "/getUser", method = RequestMethod.GET)

 @ApiOperation(value = "获取用户", notes = "根据UserVo获取用户")  

 @ResponseBody

  public Result<UserVo> getUser() {  

     UserVo userVo=new UserVo();

     userVo.setUserId(System.currentTimeMillis());

     userVo.setUserName("UserName");

        return new Result<UserVo>(Constants.SUCCESS,Constants.MSG_SUCCESS,userVo);

 }

SwaggerConfig类编写示例

@Configuration

@EnableSwagger2

public class SwaggerConfig {

    @Bean

    public Docket userApi() {

        return new Docket(DocumentationType.SWAGGER_2)

                .groupName("用户")

                .select()  // 选择那些路径和api会生成document

                .apis(RequestHandlerSelectors.basePackage("com.zyx.controller"))

                .paths(PathSelectors.any()) // 对所有路径进行监控

                .build()

                .apiInfo(userInfo());

    }

    private ApiInfo userInfo() {

        ApiInfo apiInfo = new ApiInfo("用户相关接口",//大标题

                "用户有关的接口，包括增加删除用户",//小标题

                "0.1",//版本

                "杭州",

                new Contact("zyx", "", ""),// 作者

                "swagger url",//链接显示文字

                ""//网站链接

        );

        return apiInfo;

    }

    @Bean

    public Docket otherApi() {

        return new Docket(DocumentationType.SWAGGER_2)

                .groupName("其它")

                .select()  // 选择那些路径和api会生成document

                .apis(RequestHandlerSelectors.basePackage("com.zyx.controller"))

                .paths(PathSelectors.any()) // 对所有路径进行监控

                .build()

                .apiInfo(otherInfo());

    }

    private ApiInfo otherInfo() {

        ApiInfo apiInfo = new ApiInfo("其它相关接口",//大标题

                "其它有关的接口，包括增加删除其它",//小标题

                "0.1",//版本

                "杭州",

                new Contact("zyx_other", "", ""),// 作者

                "点击",//链接显示文字

                ""//网站链接

        );

        return apiInfo;

    }

}

  

注:将SwaggerConfig在Spring注入管理 <bean class="com.demo.config.SwaggerConfig"/>

@ApiModel(value = "用户信息")

public class UserVo {

    @ApiModelProperty(value = "用户id", required = true)

    private long userId;

    @ApiModelProperty(value = "昵称", required = true)

    private String userName;

    public long getUserId() {

        return userId;

    }

    public void setUserId(long userId) {

        this.userId = userId;

    }

public String getUserName() {

return userName;

}

public void setUserName(String userName) {

this.userName = userName;

}

}

4. 界面展示

 

 

 

在浏览器输入地址：http://localhost:8080/swagger-ui.html