大家好，我是讯享网，很高兴认识大家。



当下很多项目都采用前后端分离的开发模式，前端和后断的工作由不同的团队完成。在这种开发模式下，维持一根及时更新并且完整的Rest API文档会极大的提高我们的工作效率。传统的wen是由后端开发人员手动编写，这种方式很难保证文档的及时性，久而久之这种方式书写的文档也就失去了意义。Swagger优点：

1、代码变，文档变。只需要少量的注解，Swagger 就可以根据代码自动生成 API 文档，很好的保证了文档的时效性。

2、跨语言性，支持 40 多种语言。

3、Swagger UI 呈现出来的是一份可交互式的 API 文档，我们可以直接在文档页面尝试 API 的调用，省去了准备复杂的调用参数的过程。

4、还可以将文档规范导入相关的工具（例如 Postman、SoapUI）, 这些工具将会为我们自动地创建自动化测试。

    <groupId>io.springfox

    <artifactId>springfox-swagger2

    <version>2.7.0

    <groupId>io.springfox

    <artifactId>springfox-swagger-ui

    <version>2.7.0

</dependency>

@Configuration

@EnableSwagger2

public class SwaggerConfig {

@Bean

    public DocketproductApi(){

return new Docket(DocumentationType.SWAGGER_2)

.apiInfo(apiInfo())

.select()

.apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))

.paths(PathSelectors.any())

.build();

    }

private ApiInfoapiInfo(){

return new ApiInfoBuilder().title(“加解密服务api”)

.description(“1.0”)

.build();

    }

}

如果在项目中使用了shiro，需要在shiro中放行swagger2的相关资源

@Api:放在请求的类上，与@Controller并列，说明类的作用，如用户模块，订单类等。tags=“说明该类的作用”value=“该参数没什么意义，所以不需要配置”。

@ApiOperation：”用在请求的方法上，说明方法的作用”value=“说明方法的作用”notes=“方法的备注说明”

@ApiImplicitParams：用在请求的方法上，包含一组参数说明

    @ApiImplicitParam：对单个参数的说明     

        name：参数名

        value：参数的汉字说明、解释

        required：参数是否必须传

        paramType：参数放在哪个地方

            · header –> 请求参数的获取：@RequestHeader

            · query –> 请求参数的获取：@RequestParam

            · path（用于restful接口）–> 请求参数的获取：@PathVariable

            · body（请求体）–>  @RequestBody User user

讯享网

            · form（普通表单提交）   

        dataType：参数类型，默认String，其它值dataType=“int”     

        defaultValue：参数的默认值

@ApiOperation(value=“用户登录”,notes=“随边说点啥”)@ApiImplicitParams({@ApiImplicitParam(name=“mobile”,value=“手机号”,required=true,paramType=“form”),@ApiImplicitParam(name=“password”,value=“密码”,required=true,paramType=“form”),@ApiImplicitParam(name=“age”,value=“年龄”,required=true,paramType=“form”,dataType=“Integer”)})

@PostMapping(“/login”)

publicAjaxResultlogin(@RequestParamStringmobile,@RequestParamStringpassword,@RequestParamIntegerage){//TODOreturnAjaxResult.OK();}

@ApiResponses：方法返回对象的说明

    @ApiResponse：每个参数的说明

        code：数字，例如400

        message：信息，例如”请求参数没填好”

        response：抛出异常的类

@ApiOperation(value =“对称加密算法加密”, notes =“使用设置的默认对称加密算法对数据进行加密，返回值中的data为string类型，加密失败data为null”)

@PostMapping(“symmetryEncryption”)

@ApiResponses(value = {

@ApiResponse(code =1000, message =“成功”), @ApiResponse(code =1001, message =“失败”)

})

public ResultsymmetryEncryption(@ApiParam(“要加密的数据”)@RequestParam(value =“data”) String data) {

try {

String algorithm = SystemParameter.getSymmetryAlgorithm();

        EncryptionAlgorithm encryptionAlgorithm = SymmetryEncryptUtil.algorithmType(algorithm);

        String encryption = SymmetryEncryptUtil.encryption(encryptionAlgorithm, data, path);

        return new Result<>(1000, “”, encryption);

    }catch (Exception e) {

e.printStackTrace();

        return new Result<>(1001, “”, null);

    }

}

对一个参数进行说明

@ApiModel：用于JavaBean的类上面，表示此JavaBean整体的信息（这种一般用在post创建的时候，使用@RequestBody这样的场景，请求参数无法使用@ApiImplicitParam注解进行描述的时候）

@ApiModelProperty:用在JavaBean的属性上面，说明属性的含义

@ApiModel(“修改密码所需参数封装类”)

publicclassPasswordModel{

@ApiModelProperty(“账户Id”)

privateStringaccountId;

}

配置好Swagger2并适当添加注解后，启动SpringBoot应用，访问http://localhost:8080/swagger-ui.html 即可浏览API文档。合理使用上面的注解会极大的提高我们文档的可读性。

打开postman->import->import Form Link，输入文档url

代码示例：https://github.com/ChunyuePeng/swagger2demo.git